@codluv/versionguard 0.8.0 → 0.9.0

package/dist/chunks/src-BPMDUQfR.js

@@ -0,0 +1,4741 @@
+import * as childProcess from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import * as yaml from "js-yaml";
+import { parse } from "smol-toml";
+import { globSync } from "glob";
+import { fileURLToPath } from "node:url";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/scheme-rules.ts
+/**
+* Validates a pre-release / modifier tag against the allowed modifiers list.
+*
+* @remarks
+* Both SemVer prerelease identifiers (e.g. `alpha` from `1.2.3-alpha.1`) and
+* CalVer modifiers (e.g. `rc` from `2026.3.0-rc2`) share the same validation
+* logic: strip trailing digits/dots to get the base tag, then check the
+* whitelist.
+*
+* @param modifier - Raw modifier string (e.g. `"alpha.1"`, `"rc2"`, `"dev"`).
+* @param schemeRules - Scheme rules containing the allowed modifiers list.
+* @returns A validation error when the modifier is disallowed, otherwise `null`.
+*
+* @example
+* ```ts
+* import { validateModifier } from './scheme-rules';
+*
+* const error = validateModifier('alpha.1', { maxNumericSegments: 3, allowedModifiers: ['dev', 'alpha', 'beta', 'rc'] });
+* // => null (allowed)
+* ```
+*
+* @internal
+* @since 0.6.0
+*/
+function validateModifier(modifier, schemeRules) {
+	if (!modifier || !schemeRules?.allowedModifiers) return null;
+	const baseModifier = modifier.replace(/[\d.]+$/, "") || modifier;
+	if (!schemeRules.allowedModifiers.includes(baseModifier)) return {
+		message: `Modifier "${modifier}" is not allowed. Allowed: ${schemeRules.allowedModifiers.join(", ")}`,
+		severity: "error"
+	};
+	return null;
+}
+//#endregion
+//#region src/calver.ts
+/**
+* Calendar version parsing, formatting, and comparison helpers.
+*
+* @remarks
+* Supports the full calver.org specification with all standard tokens:
+* Year (`YYYY`, `YY`, `0Y`), Month (`MM`, `M`, `0M`), Week (`WW`, `0W`),
+* Day (`DD`, `D`, `0D`), and Counter (`MICRO`/`PATCH`).
+*
+* `MICRO` is the CalVer-standard name for the counter segment.
+* `PATCH` is accepted as a SemVer-familiar alias and behaves identically.
+*
+* @packageDocumentation
+*/
+var calver_exports = /* @__PURE__ */ __exportAll({
+	compare: () => compare$1,
+	format: () => format$1,
+	getCurrentVersion: () => getCurrentVersion,
+	getNextVersions: () => getNextVersions,
+	getRegexForFormat: () => getRegexForFormat,
+	increment: () => increment$1,
+	isValidCalVerFormat: () => isValidCalVerFormat,
+	parse: () => parse$2,
+	parseFormat: () => parseFormat,
+	validate: () => validate$2
+});
+/** All recognized CalVer tokens. */
+var VALID_TOKENS = new Set([
+	"YYYY",
+	"YY",
+	"0Y",
+	"MM",
+	"M",
+	"0M",
+	"WW",
+	"0W",
+	"DD",
+	"D",
+	"0D",
+	"MICRO",
+	"PATCH"
+]);
+/** Year tokens. */
+var YEAR_TOKENS = new Set([
+	"YYYY",
+	"YY",
+	"0Y"
+]);
+/** Month tokens. */
+var MONTH_TOKENS = new Set([
+	"MM",
+	"M",
+	"0M"
+]);
+/** Week tokens. */
+var WEEK_TOKENS = new Set(["WW", "0W"]);
+/** Day tokens. */
+var DAY_TOKENS = new Set([
+	"DD",
+	"D",
+	"0D"
+]);
+/** Counter tokens (MICRO is canonical, PATCH is alias). */
+var COUNTER_TOKENS = new Set(["MICRO", "PATCH"]);
+/**
+* Validates that a CalVer format string is composed of valid tokens
+* and follows structural rules.
+*
+* @remarks
+* Structural rules enforced:
+* - Must have at least 2 segments
+* - First segment must be a year token
+* - Week tokens and Month/Day tokens are mutually exclusive
+* - Counter (MICRO/PATCH) can only appear as the last segment
+*
+* @param formatStr - Format string to validate.
+* @returns `true` when the format is valid.
+*
+* @example
+* ```ts
+* import { isValidCalVerFormat } from 'versionguard';
+*
+* isValidCalVerFormat('YYYY.MM.MICRO'); // true
+* isValidCalVerFormat('INVALID');        // false
+* ```
+*
+* @public
+* @since 0.3.0
+*/
+function isValidCalVerFormat(formatStr) {
+	const tokens = formatStr.split(".");
+	if (tokens.length < 2) return false;
+	if (!tokens.every((t) => VALID_TOKENS.has(t))) return false;
+	if (!YEAR_TOKENS.has(tokens[0])) return false;
+	const hasWeek = tokens.some((t) => WEEK_TOKENS.has(t));
+	const hasMonthOrDay = tokens.some((t) => MONTH_TOKENS.has(t) || DAY_TOKENS.has(t));
+	if (hasWeek && hasMonthOrDay) return false;
+	const counterIndex = tokens.findIndex((t) => COUNTER_TOKENS.has(t));
+	if (counterIndex !== -1 && counterIndex !== tokens.length - 1) return false;
+	return true;
+}
+/**
+* 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 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.MICRO');
+* // => { year: 'YYYY', month: 'MM', counter: 'MICRO' }
+* ```
+*
+* @public
+* @since 0.1.0
+*/
+function parseFormat(calverFormat) {
+	const tokens = calverFormat.split(".");
+	const result = { year: tokens[0] };
+	for (let i = 1; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (MONTH_TOKENS.has(token)) result.month = token;
+		else if (WEEK_TOKENS.has(token)) result.week = token;
+		else if (DAY_TOKENS.has(token)) result.day = token;
+		else if (COUNTER_TOKENS.has(token)) result.counter = token;
+	}
+	return result;
+}
+/** The optional modifier suffix pattern (e.g., `-alpha.1`, `-rc2`). */
+var MODIFIER_PATTERN = "(?:-([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?";
+/**
+* Maps a CalVer token to a strict regex capture group.
+*
+* Patterns enforce value-level constraints (e.g., month 1-12, day 1-31)
+* at the regex level, not just structurally.
+*/
+function tokenPattern(token) {
+	switch (token) {
+		case "YYYY": return "([1-9]\\d{3})";
+		case "YY": return "(\\d{1,3})";
+		case "0Y": return "(\\d{2,3})";
+		case "MM":
+		case "M": return "([1-9]|1[0-2])";
+		case "0M": return "(0[1-9]|1[0-2])";
+		case "WW": return "([1-9]|[1-4]\\d|5[0-3])";
+		case "0W": return "(0[1-9]|[1-4]\\d|5[0-3])";
+		case "DD":
+		case "D": return "([1-9]|[12]\\d|3[01])";
+		case "0D": return "(0[1-9]|[12]\\d|3[01])";
+		case "MICRO":
+		case "PATCH": return "(0|[1-9]\\d*)";
+		default: throw new Error(`Unsupported CalVer token: ${token}`);
+	}
+}
+/**
+* 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
+*/
+function getRegexForFormat(calverFormat) {
+	const pattern = calverFormat.split(".").map(tokenPattern).join("\\.");
+	return new RegExp(`^${pattern}${MODIFIER_PATTERN}$`);
+}
+/**
+* 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.3.0', 'YYYY.M.MICRO')?.month;
+* // => 3
+* ```
+*
+* @see {@link validate} to apply date-range and future-date validation.
+* @public
+* @since 0.1.0
+*/
+function parse$2(version, calverFormat) {
+	const match = version.match(getRegexForFormat(calverFormat));
+	if (!match) return null;
+	const definition = parseFormat(calverFormat);
+	const yearToken = definition.year;
+	let year = Number.parseInt(match[1], 10);
+	if (yearToken === "YY" || yearToken === "0Y") year = 2e3 + year;
+	let cursor = 2;
+	let month;
+	let day;
+	let patch;
+	if (definition.month) {
+		month = Number.parseInt(match[cursor], 10);
+		cursor += 1;
+	}
+	if (definition.week) {
+		month = Number.parseInt(match[cursor], 10);
+		cursor += 1;
+	}
+	if (definition.day) {
+		day = Number.parseInt(match[cursor], 10);
+		cursor += 1;
+	}
+	if (definition.counter) {
+		patch = Number.parseInt(match[cursor], 10);
+		cursor += 1;
+	}
+	const modifier = match[cursor] || void 0;
+	return {
+		year,
+		month: month ?? 1,
+		day,
+		patch,
+		modifier,
+		format: calverFormat,
+		raw: version
+	};
+}
+/**
+* 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.
+* @param schemeRules - Optional scheme rules for modifier validation and segment count warnings.
+* @returns A validation result containing any discovered errors and the parsed version on success.
+*
+* @example
+* ```ts
+* import { validate } from 'versionguard';
+*
+* validate('2026.3.0', 'YYYY.M.MICRO', false).valid;
+* // => true
+* ```
+*
+* @public
+* @since 0.1.0
+*/
+function validate$2(version, calverFormat, preventFutureDates = true, schemeRules) {
+	const errors = [];
+	const parsed = parse$2(version, calverFormat);
+	if (!parsed) return {
+		valid: false,
+		errors: [{
+			message: `Invalid CalVer format: "${version}". Expected format: ${calverFormat}`,
+			severity: "error"
+		}]
+	};
+	const definition = parseFormat(calverFormat);
+	if (definition.month && (parsed.month < 1 || parsed.month > 12)) errors.push({
+		message: `Invalid month: ${parsed.month}. Must be between 1 and 12.`,
+		severity: "error"
+	});
+	if (definition.week && (parsed.month < 1 || parsed.month > 53)) errors.push({
+		message: `Invalid week: ${parsed.month}. Must be between 1 and 53.`,
+		severity: "error"
+	});
+	if (parsed.day !== void 0) {
+		if (parsed.day < 1 || parsed.day > 31) errors.push({
+			message: `Invalid day: ${parsed.day}. Must be between 1 and 31.`,
+			severity: "error"
+		});
+		else if (definition.month) {
+			const daysInMonth = new Date(parsed.year, parsed.month, 0).getDate();
+			if (parsed.day > daysInMonth) errors.push({
+				message: `Invalid day: ${parsed.day}. ${parsed.year}-${String(parsed.month).padStart(2, "0")} has only ${daysInMonth} days.`,
+				severity: "error"
+			});
+		}
+	}
+	if (preventFutureDates) {
+		const now = /* @__PURE__ */ new Date();
+		const currentYear = now.getFullYear();
+		const currentMonth = now.getMonth() + 1;
+		const currentDay = now.getDate();
+		if (parsed.year > currentYear) errors.push({
+			message: `Future year not allowed: ${parsed.year}. Current year is ${currentYear}.`,
+			severity: "error"
+		});
+		else if (definition.month && parsed.year === currentYear && parsed.month > currentMonth) errors.push({
+			message: `Future month not allowed: ${parsed.year}.${parsed.month}. Current month is ${currentMonth}.`,
+			severity: "error"
+		});
+		else if (definition.month && parsed.year === currentYear && parsed.month === currentMonth && parsed.day !== void 0 && parsed.day > currentDay) errors.push({
+			message: `Future day not allowed: ${parsed.year}.${parsed.month}.${parsed.day}. Current day is ${currentDay}.`,
+			severity: "error"
+		});
+	}
+	if (parsed.modifier) {
+		const modifierError = validateModifier(parsed.modifier, schemeRules);
+		if (modifierError) errors.push(modifierError);
+	}
+	if (schemeRules?.maxNumericSegments) {
+		const segmentCount = calverFormat.split(".").length;
+		if (segmentCount > schemeRules.maxNumericSegments) errors.push({
+			message: `Format has ${segmentCount} segments, convention recommends ${schemeRules.maxNumericSegments} or fewer`,
+			severity: "warning"
+		});
+	}
+	return {
+		valid: errors.filter((e) => e.severity === "error").length === 0,
+		errors,
+		version: {
+			type: "calver",
+			version: parsed
+		}
+	};
+}
+function formatToken(token, value) {
+	switch (token) {
+		case "0M":
+		case "0D":
+		case "0W":
+		case "0Y": return String(token === "0Y" ? value % 100 : value).padStart(2, "0");
+		case "YY": return String(value % 100).padStart(2, "0");
+		default: return String(value);
+	}
+}
+/**
+* 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
+*/
+function format$1(version) {
+	const definition = parseFormat(version.format);
+	const parts = [formatToken(definition.year, version.year)];
+	if (definition.month) parts.push(formatToken(definition.month, version.month));
+	if (definition.week) parts.push(formatToken(definition.week, version.month));
+	if (definition.day) parts.push(formatToken(definition.day, version.day ?? 1));
+	if (definition.counter) parts.push(formatToken(definition.counter, version.patch ?? 0));
+	const base = parts.join(".");
+	return version.modifier ? `${base}-${version.modifier}` : base;
+}
+/**
+* Creates the current CalVer string for a format.
+*
+* @remarks
+* This helper derives its values from the provided date and initializes any counter to `0`.
+* It is useful for generating a same-day baseline before incrementing counter-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.M.MICRO', new Date('2026-03-21T00:00:00Z'));
+* // => '2026.3.0'
+* ```
+*
+* @public
+* @since 0.1.0
+*/
+function getCurrentVersion(calverFormat, now = /* @__PURE__ */ new Date()) {
+	const definition = parseFormat(calverFormat);
+	return format$1({
+		year: now.getFullYear(),
+		month: now.getMonth() + 1,
+		day: definition.day ? now.getDate() : void 0,
+		patch: definition.counter ? 0 : void 0,
+		format: calverFormat,
+		raw: ""
+	});
+}
+/**
+* Compares two CalVer strings using a shared format.
+*
+* @remarks
+* Comparison is performed component-by-component in year, month, day, then counter order.
+* Missing day and counter 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.3.2', '2026.3.1', 'YYYY.M.MICRO');
+* // => 1
+* ```
+*
+* @public
+* @since 0.1.0
+*/
+function compare$1(a, b, calverFormat) {
+	const left = parse$2(a, calverFormat);
+	const right = parse$2(b, calverFormat);
+	if (!left || !right) throw new Error(`Invalid CalVer comparison between "${a}" and "${b}"`);
+	for (const key of [
+		"year",
+		"month",
+		"day",
+		"patch"
+	]) {
+		const leftValue = left[key] ?? 0;
+		const rightValue = right[key] ?? 0;
+		if (leftValue !== rightValue) return leftValue > rightValue ? 1 : -1;
+	}
+	return 0;
+}
+/**
+* Increments a CalVer string.
+*
+* @remarks
+* Counter-based formats increment the existing counter. Formats without a counter are
+* promoted to a counter-based output by appending `.MICRO` 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.3.1', 'YYYY.M.MICRO');
+* // => '2026.3.2'
+* ```
+*
+* @public
+* @since 0.1.0
+*/
+function increment$1(version, calverFormat) {
+	const parsed = parse$2(version, calverFormat);
+	if (!parsed) throw new Error(`Invalid CalVer version: ${version}`);
+	const definition = parseFormat(calverFormat);
+	const next = {
+		...parsed,
+		raw: version
+	};
+	if (definition.counter) next.patch = (parsed.patch ?? 0) + 1;
+	else {
+		next.patch = 0;
+		next.format = `${calverFormat}.MICRO`;
+	}
+	return format$1(next);
+}
+/**
+* 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.3.1', 'YYYY.M.MICRO').length;
+* // => 2
+* ```
+*
+* @public
+* @since 0.1.0
+*/
+function getNextVersions(currentVersion, calverFormat) {
+	return [getCurrentVersion(calverFormat), increment$1(currentVersion, calverFormat)];
+}
+//#endregion
+//#region src/changelog.ts
+var CHANGELOG_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+/** Default Keep a Changelog section names. */
+var KEEP_A_CHANGELOG_SECTIONS = [
+	"Added",
+	"Changed",
+	"Deprecated",
+	"Removed",
+	"Fixed",
+	"Security"
+];
+/**
+* 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.
+*
+* When `structure.enforceStructure` is `true`, section headers (`### Name`)
+* are validated against the allowed list and empty sections produce warnings.
+*
+* @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.
+* @param structure - Optional structure enforcement options.
+* @returns The result of validating the changelog file.
+* @example
+* ```ts
+* import { validateChangelog } from 'versionguard';
+*
+* const result = validateChangelog('CHANGELOG.md', '1.2.0', true, true, {
+*   enforceStructure: true,
+*   sections: ['Added', 'Changed', 'Fixed'],
+* });
+* ```
+*/
+function validateChangelog(changelogPath, version, strict = true, requireEntry = true, structure) {
+	if (!fs.existsSync(changelogPath)) return {
+		valid: !requireEntry,
+		errors: requireEntry ? [`Changelog not found: ${changelogPath}`] : [],
+		hasEntryForVersion: false
+	};
+	const errors = [];
+	const content = fs.readFileSync(changelogPath, "utf-8");
+	if (!content.startsWith("# Changelog")) errors.push("Changelog must start with \"# Changelog\"");
+	if (!content.includes("## [Unreleased]")) errors.push("Changelog must have an [Unreleased] section");
+	const versionHeader = `## [${version}]`;
+	const hasEntryForVersion = content.includes(versionHeader);
+	if (requireEntry && !hasEntryForVersion) errors.push(`Changelog must have an entry for version ${version}`);
+	if (strict) {
+		if (!content.includes("[Unreleased]:")) errors.push("Changelog should include compare links at the bottom");
+		const versionHeaderMatch = content.match(new RegExp(`## \\[${escapeRegExp$1(version)}\\] - ([^\r\n]+)`));
+		if (requireEntry && hasEntryForVersion) {
+			if (!versionHeaderMatch) errors.push(`Version ${version} entry must use "## [${version}] - YYYY-MM-DD" format`);
+			else if (!CHANGELOG_DATE_REGEX.test(versionHeaderMatch[1])) errors.push(`Version ${version} entry date must use YYYY-MM-DD format`);
+		}
+	}
+	if (structure?.enforceStructure) {
+		const sectionErrors = validateSections(content, structure.sections ?? KEEP_A_CHANGELOG_SECTIONS);
+		errors.push(...sectionErrors);
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		hasEntryForVersion
+	};
+}
+/**
+* Validates that all `### SectionName` headers use allowed names
+* and flags empty sections.
+*/
+function validateSections(content, allowed) {
+	const errors = [];
+	const lines = content.split("\n");
+	for (let i = 0; i < lines.length; i++) {
+		const sectionMatch = lines[i].match(/^### (.+)/);
+		if (!sectionMatch) continue;
+		const sectionName = sectionMatch[1].trim();
+		if (!allowed.includes(sectionName)) errors.push(`Invalid changelog section "### ${sectionName}" (line ${i + 1}). Allowed: ${allowed.join(", ")}`);
+		const nextContentLine = lines.slice(i + 1).find((l) => l.trim().length > 0);
+		if (!nextContentLine || nextContentLine.startsWith("#")) errors.push(`Empty changelog section "### ${sectionName}" (line ${i + 1})`);
+	}
+	return errors;
+}
+/**
+* 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');
+* ```
+*/
+function addVersionEntry(changelogPath, version, date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)) {
+	if (!fs.existsSync(changelogPath)) throw new Error(`Changelog not found: ${changelogPath}`);
+	const content = fs.readFileSync(changelogPath, "utf-8");
+	if (content.includes(`## [${version}]`)) return;
+	const block = `## [${version}] - ${date}\n\n### Added\n\n- Describe changes here.\n\n`;
+	const unreleasedMatch = content.match(/## \[Unreleased\]\r?\n(?:\r?\n)?/);
+	if (!unreleasedMatch || unreleasedMatch.index === void 0) throw new Error("Changelog must have an [Unreleased] section");
+	const insertIndex = unreleasedMatch.index + unreleasedMatch[0].length;
+	const updated = `${content.slice(0, insertIndex)}${block}${content.slice(insertIndex)}`;
+	fs.writeFileSync(changelogPath, updated, "utf-8");
+}
+/**
+* Detects whether a changelog has been mangled by Changesets.
+*
+* @remarks
+* Changesets prepends version content above the Keep a Changelog preamble,
+* producing `## 0.4.0` (no brackets, no date) before the "All notable changes"
+* paragraph. This function detects that pattern.
+*
+* @param changelogPath - Path to the changelog file.
+* @returns `true` when the changelog appears to be mangled by Changesets.
+*
+* @example
+* ```ts
+* import { isChangesetMangled } from 'versionguard';
+*
+* if (isChangesetMangled('CHANGELOG.md')) {
+*   fixChangesetMangling('CHANGELOG.md');
+* }
+* ```
+*
+* @public
+* @since 0.4.0
+*/
+function isChangesetMangled(changelogPath) {
+	if (!fs.existsSync(changelogPath)) return false;
+	const content = fs.readFileSync(changelogPath, "utf-8");
+	return /^## \d+\.\d+/m.test(content) && content.includes("## [Unreleased]");
+}
+/** Maps Changesets section names to Keep a Changelog section names. */
+var SECTION_MAP = {
+	"Major Changes": "Changed",
+	"Minor Changes": "Added",
+	"Patch Changes": "Fixed"
+};
+/**
+* Fixes a Changesets-mangled changelog into proper Keep a Changelog format.
+*
+* @remarks
+* This function:
+* 1. Extracts the version number and content prepended by Changesets
+* 2. Converts Changesets section names (Minor Changes, Patch Changes) to
+*    Keep a Changelog names (Added, Fixed)
+* 3. Strips commit hashes from entry lines
+* 4. Adds the date and brackets to the version header
+* 5. Inserts the entry after `## [Unreleased]` in the correct position
+* 6. Restores the preamble to its proper location
+*
+* @param changelogPath - Path to the changelog file to fix.
+* @param date - Release date in `YYYY-MM-DD` format.
+* @returns `true` when the file was modified, `false` when no fix was needed.
+*
+* @example
+* ```ts
+* import { fixChangesetMangling } from 'versionguard';
+*
+* const fixed = fixChangesetMangling('CHANGELOG.md');
+* ```
+*
+* @public
+* @since 0.4.0
+*/
+function fixChangesetMangling(changelogPath, date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)) {
+	if (!fs.existsSync(changelogPath)) return false;
+	const content = fs.readFileSync(changelogPath, "utf-8");
+	const versionMatch = content.match(/^## (\d+\.\d+\.\d+[^\n]*)\n/m);
+	if (!versionMatch || versionMatch.index === void 0) return false;
+	const fullHeader = versionMatch[0];
+	if (fullHeader.includes("[")) return false;
+	const version = versionMatch[1].trim();
+	if (content.includes(`## [${version}]`)) return false;
+	const startIndex = versionMatch.index;
+	const preambleMatch = content.indexOf("All notable changes", startIndex);
+	const unreleasedMatch = content.indexOf("## [Unreleased]", startIndex);
+	let endIndex;
+	if (preambleMatch !== -1 && preambleMatch < unreleasedMatch) endIndex = preambleMatch;
+	else if (unreleasedMatch !== -1) endIndex = unreleasedMatch;
+	else return false;
+	const newEntry = `## [${version}] - ${date}\n\n${transformChangesetsContent(content.slice(startIndex + fullHeader.length, endIndex).trim())}\n\n`;
+	const beforeChangesets = content.slice(0, startIndex);
+	const afterChangesets = content.slice(endIndex);
+	const unreleasedInAfter = afterChangesets.indexOf("## [Unreleased]");
+	if (unreleasedInAfter === -1) {
+		const rebuilt = `${beforeChangesets}${newEntry}${afterChangesets}`;
+		fs.writeFileSync(changelogPath, rebuilt, "utf-8");
+		return true;
+	}
+	const unreleasedLineEnd = afterChangesets.indexOf("\n", unreleasedInAfter);
+	const withLinks = updateCompareLinks(`${beforeChangesets}${unreleasedLineEnd !== -1 ? afterChangesets.slice(0, unreleasedLineEnd + 1) : afterChangesets}\n${newEntry}${unreleasedLineEnd !== -1 ? afterChangesets.slice(unreleasedLineEnd + 1) : ""}`, version);
+	fs.writeFileSync(changelogPath, withLinks, "utf-8");
+	return true;
+}
+/**
+* Transforms Changesets-style content into Keep a Changelog sections.
+*
+* Converts "### Minor Changes" → "### Added", strips commit hashes, etc.
+*/
+function transformChangesetsContent(block) {
+	const lines = block.split("\n");
+	const result = [];
+	for (const line of lines) {
+		const sectionMatch = line.match(/^### (.+)/);
+		if (sectionMatch) {
+			const mapped = SECTION_MAP[sectionMatch[1]] ?? sectionMatch[1];
+			result.push(`### ${mapped}`);
+			continue;
+		}
+		const entryMatch = line.match(/^(\s*-\s+)[a-f0-9]{7,}: (?:feat|fix|chore|docs|refactor|perf|test|ci|build|style)(?:\([^)]*\))?: (.+)/);
+		if (entryMatch) {
+			result.push(`${entryMatch[1]}${entryMatch[2]}`);
+			continue;
+		}
+		const simpleHashMatch = line.match(/^(\s*-\s+)[a-f0-9]{7,}: (.+)/);
+		if (simpleHashMatch) {
+			result.push(`${simpleHashMatch[1]}${simpleHashMatch[2]}`);
+			continue;
+		}
+		result.push(line);
+	}
+	return result.join("\n");
+}
+/**
+* Updates the compare links section at the bottom of the changelog.
+*/
+function updateCompareLinks(content, version) {
+	const unreleasedLinkRegex = /\[Unreleased\]: (https:\/\/[^\s]+\/compare\/v)([\d.]+)(\.\.\.HEAD)/;
+	const match = content.match(unreleasedLinkRegex);
+	if (match) {
+		const baseUrl = match[1].replace(/v$/, "");
+		const previousVersion = match[2];
+		const newUnreleasedLink = `[Unreleased]: ${baseUrl}v${version}...HEAD`;
+		const newVersionLink = `[${version}]: ${baseUrl}v${previousVersion}...v${version}`;
+		let updated = content.replace(unreleasedLinkRegex, newUnreleasedLink);
+		if (!updated.includes(`[${version}]:`)) updated = updated.replace(newUnreleasedLink, `${newUnreleasedLink}\n${newVersionLink}`);
+		return updated;
+	}
+	return content;
+}
+function escapeRegExp$1(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region src/github/dependabot.ts
+/**
+* Dependabot configuration generation from detected project manifests.
+*
+* @packageDocumentation
+*/
+/**
+* Maps VersionGuard manifest source types to Dependabot package-ecosystem values.
+*
+* @remarks
+* Returns `null` for sources that have no Dependabot equivalent (VERSION files,
+* git tags, custom regex). The `auto` source is resolved at detection time,
+* not mapped directly.
+*
+* @public
+* @since 0.9.0
+*/
+var MANIFEST_TO_ECOSYSTEM = {
+	auto: null,
+	"package.json": "npm",
+	"composer.json": "composer",
+	"Cargo.toml": "cargo",
+	"pyproject.toml": "pip",
+	"pubspec.yaml": "pub",
+	"pom.xml": "maven",
+	VERSION: null,
+	"git-tag": null,
+	custom: null
+};
+/**
+* Generates Dependabot YAML configuration from detected manifests.
+*
+* @remarks
+* Each detected manifest is mapped to its Dependabot ecosystem. A
+* `github-actions` entry is always appended since any GitHub-hosted
+* project benefits from action version updates.
+*
+* @param manifests - Detected manifest source types from the project.
+* @returns The Dependabot configuration as a YAML string.
+*
+* @example
+* ```ts
+* import { generateDependabotConfig } from 'versionguard';
+*
+* const config = generateDependabotConfig(['package.json', 'Cargo.toml']);
+* ```
+*
+* @public
+* @since 0.9.0
+*/
+function generateDependabotConfig(manifests) {
+	const ecosystems = /* @__PURE__ */ new Set();
+	for (const manifest of manifests) {
+		const ecosystem = MANIFEST_TO_ECOSYSTEM[manifest];
+		if (ecosystem) ecosystems.add(ecosystem);
+	}
+	const updates = [];
+	for (const ecosystem of ecosystems) updates.push({
+		"package-ecosystem": ecosystem,
+		directory: "/",
+		schedule: { interval: "weekly" },
+		groups: { "minor-and-patch": { "update-types": ["minor", "patch"] } }
+	});
+	updates.push({
+		"package-ecosystem": "github-actions",
+		directory: "/",
+		schedule: { interval: "weekly" }
+	});
+	return yaml.dump({
+		version: 2,
+		updates
+	}, {
+		indent: 2,
+		lineWidth: 120,
+		noRefs: true,
+		quotingType: "\"",
+		forceQuotes: false
+	});
+}
+/**
+* Writes a Dependabot configuration file to `.github/dependabot.yml`.
+*
+* @param cwd - Project directory.
+* @param content - YAML content to write.
+* @returns The absolute path to the created file.
+*
+* @public
+* @since 0.9.0
+*/
+function writeDependabotConfig(cwd, content) {
+	const dir = path.join(cwd, ".github");
+	fs.mkdirSync(dir, { recursive: true });
+	const filePath = path.join(dir, "dependabot.yml");
+	fs.writeFileSync(filePath, content, "utf-8");
+	return filePath;
+}
+/**
+* Checks whether `.github/dependabot.yml` exists in the project.
+*
+* @param cwd - Project directory.
+* @returns `true` when the file exists.
+*
+* @public
+* @since 0.9.0
+*/
+function dependabotConfigExists(cwd) {
+	return fs.existsSync(path.join(cwd, ".github", "dependabot.yml"));
+}
+//#endregion
+//#region src/hooks.ts
+var HOOK_NAMES$1 = [
+	"pre-commit",
+	"pre-push",
+	"post-tag"
+];
+/** Markers that delimit the VG block within a composite hook script. */
+var VG_BLOCK_START = "# >>> versionguard >>>";
+var VG_BLOCK_END = "# <<< versionguard <<<";
+/**
+* Installs VersionGuard-managed Git hooks in a repository.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* When a hook file already exists from another tool (Husky, lefthook, etc.),
+* VersionGuard **appends** its validation block instead of overwriting.
+* The block is delimited by markers so it can be cleanly removed later.
+*
+* If the hook already contains a VersionGuard block, it is replaced in-place
+* (idempotent).
+*
+* @param config - Git configuration that selects which hooks to install.
+* @param cwd - Repository directory where hooks should be installed.
+* @example
+* ```ts
+* import { getDefaultConfig, installHooks } from 'versionguard';
+*
+* installHooks(getDefaultConfig().git, process.cwd());
+* ```
+*/
+function installHooks(config, cwd = process.cwd()) {
+	const gitDir = findGitDir(cwd);
+	if (!gitDir) throw new Error("Not a git repository. Run `git init` first.");
+	const hooksDir = path.join(gitDir, "hooks");
+	fs.mkdirSync(hooksDir, { recursive: true });
+	for (const hookName of HOOK_NAMES$1) if (config.hooks[hookName]) {
+		const hookPath = path.join(hooksDir, hookName);
+		const vgBlock = generateHookBlock(hookName);
+		if (fs.existsSync(hookPath)) {
+			const existing = fs.readFileSync(hookPath, "utf-8");
+			if (existing.includes(VG_BLOCK_START)) {
+				const updated = replaceVgBlock(existing, vgBlock);
+				fs.writeFileSync(hookPath, updated, {
+					encoding: "utf-8",
+					mode: 493
+				});
+			} else if (isLegacyVgHook(existing)) fs.writeFileSync(hookPath, `#!/bin/sh\n\n${vgBlock}\n`, {
+				encoding: "utf-8",
+				mode: 493
+			});
+			else {
+				const appended = `${existing.trimEnd()}\n\n${vgBlock}\n`;
+				fs.writeFileSync(hookPath, appended, {
+					encoding: "utf-8",
+					mode: 493
+				});
+			}
+		} else fs.writeFileSync(hookPath, `#!/bin/sh\n\n${vgBlock}\n`, {
+			encoding: "utf-8",
+			mode: 493
+		});
+	}
+}
+/**
+* Removes VersionGuard-managed Git hooks from a repository.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* Only the VersionGuard block (delimited by markers) is removed.
+* Other hook content from Husky, lefthook, etc. is preserved.
+* If the hook becomes empty after removal, the file is deleted.
+*
+* @param cwd - Repository directory whose hooks should be cleaned up.
+* @example
+* ```ts
+* import { uninstallHooks } from 'versionguard';
+*
+* uninstallHooks(process.cwd());
+* ```
+*/
+function uninstallHooks(cwd = process.cwd()) {
+	const gitDir = findGitDir(cwd);
+	if (!gitDir) return;
+	const hooksDir = path.join(gitDir, "hooks");
+	for (const hookName of HOOK_NAMES$1) {
+		const hookPath = path.join(hooksDir, hookName);
+		if (!fs.existsSync(hookPath)) continue;
+		const content = fs.readFileSync(hookPath, "utf-8");
+		if (!content.includes("versionguard")) continue;
+		if (content.includes(VG_BLOCK_START)) {
+			const trimmed = removeVgBlock(content).trim();
+			if (!trimmed || trimmed === "#!/bin/sh") fs.unlinkSync(hookPath);
+			else if (isLegacyVgHook(trimmed)) fs.unlinkSync(hookPath);
+			else fs.writeFileSync(hookPath, `${trimmed}\n`, {
+				encoding: "utf-8",
+				mode: 493
+			});
+		} else if (isLegacyVgHook(content)) fs.unlinkSync(hookPath);
+	}
+}
+/**
+* Finds the nearest `.git` directory by walking up from a starting directory.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This only resolves `.git` directories and returns `null` when the search
+* reaches the filesystem root without finding a repository.
+*
+* @param cwd - Directory to start searching from.
+* @returns The resolved `.git` directory path, or `null` when none is found.
+* @example
+* ```ts
+* import { findGitDir } from 'versionguard';
+*
+* const gitDir = findGitDir(process.cwd());
+* ```
+*/
+function findGitDir(cwd) {
+	let current = cwd;
+	while (true) {
+		const gitPath = path.join(current, ".git");
+		if (fs.existsSync(gitPath) && fs.statSync(gitPath).isDirectory()) return gitPath;
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+/**
+* Checks whether all VersionGuard-managed hooks are installed.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* A hook counts as installed when the file exists and contains the
+* `versionguard` invocation — either as a standalone hook or appended
+* to an existing hook from another tool.
+*
+* @param cwd - Repository directory to inspect.
+* @returns `true` when every managed hook is installed.
+* @example
+* ```ts
+* import { areHooksInstalled } from 'versionguard';
+*
+* const installed = areHooksInstalled(process.cwd());
+* ```
+*/
+function areHooksInstalled(cwd = process.cwd()) {
+	const gitDir = findGitDir(cwd);
+	if (!gitDir) return false;
+	return HOOK_NAMES$1.every((hookName) => {
+		const hookPath = path.join(gitDir, "hooks", hookName);
+		return fs.existsSync(hookPath) && fs.readFileSync(hookPath, "utf-8").includes("versionguard");
+	});
+}
+/**
+* Generates the delimited VG block for a Git hook.
+*
+* @param hookName - Name of the Git hook to generate.
+* @returns The VG block with start/end markers.
+*/
+function generateHookBlock(hookName) {
+	return `${VG_BLOCK_START}
+# VersionGuard ${hookName} hook
+# --no-install prevents accidentally downloading an unscoped package
+# if @codluv/versionguard is not installed locally
+npx --no-install versionguard validate --hook=${hookName}
+status=$?
+if [ $status -ne 0 ]; then
+  echo "VersionGuard validation failed."
+  exit $status
+fi
+${VG_BLOCK_END}`;
+}
+/**
+* Generates the shell script content for a Git hook.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* The generated script delegates to `npx versionguard validate` and exits with
+* the validation status code. Uses delimited block markers for cooperative
+* installation with other hook tools.
+*
+* @param hookName - Name of the Git hook to generate.
+* @returns Executable shell script contents for the hook.
+* @example
+* ```ts
+* import { generateHookScript } from 'versionguard';
+*
+* const script = generateHookScript('pre-commit');
+* ```
+*/
+function generateHookScript(hookName) {
+	return `#!/bin/sh\n\n${generateHookBlock(hookName)}\n`;
+}
+/** Detects a legacy VG hook (pre-marker format) that has no other tool content. */
+function isLegacyVgHook(content) {
+	if (!content.includes("versionguard validate")) return false;
+	if (content.includes(VG_BLOCK_START)) return false;
+	if (content.includes("husky")) return false;
+	if (content.includes("lefthook")) return false;
+	if (content.includes("pre-commit run")) return false;
+	return true;
+}
+/** Replaces an existing VG block within a hook script. */
+function replaceVgBlock(content, newBlock) {
+	const startIdx = content.indexOf(VG_BLOCK_START);
+	const endIdx = content.indexOf(VG_BLOCK_END);
+	if (startIdx === -1 || endIdx === -1) return content;
+	return content.slice(0, startIdx) + newBlock + content.slice(endIdx + 22);
+}
+/** Removes the VG block from a hook script. */
+function removeVgBlock(content) {
+	const startIdx = content.indexOf(VG_BLOCK_START);
+	const endIdx = content.indexOf(VG_BLOCK_END);
+	if (startIdx === -1 || endIdx === -1) return content;
+	return content.slice(0, startIdx).replace(/\n\n$/, "\n") + content.slice(endIdx + 22).replace(/^\n\n/, "\n");
+}
+//#endregion
+//#region src/sources/git-tag.ts
+/**
+* Git tag-based version source for Go, Swift, and similar ecosystems.
+*
+* @packageDocumentation
+*/
+/**
+* Reads version from the latest Git tag. Writing creates a new annotated tag.
+*
+* @remarks
+* This provider is used for languages where the version is determined
+* entirely by Git tags (Go, Swift, PHP/Packagist).
+*
+* The tag prefix (`v` by default) is auto-detected from existing tags
+* when writing, so projects using unprefixed tags (e.g. `1.0.0`) stay
+* consistent.
+*
+* @public
+* @since 0.3.0
+*/
+var GitTagSource = class {
+	/** Human-readable provider name. */
+	name = "git-tag";
+	/** Empty string since git-tag has no manifest file. */
+	manifestFile = "";
+	/**
+	* Returns `true` when `cwd` is inside a Git repository.
+	*
+	* @param cwd - Project directory to check.
+	* @returns Whether a Git repository is found.
+	*/
+	exists(cwd) {
+		try {
+			execFileSync("git", ["rev-parse", "--git-dir"], {
+				cwd,
+				stdio: [
+					"pipe",
+					"pipe",
+					"ignore"
+				]
+			});
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Reads the version string from the latest Git tag.
+	*
+	* @param cwd - Project directory containing the Git repository.
+	* @returns The version string extracted from the latest version tag.
+	*/
+	getVersion(cwd) {
+		try {
+			return this.describeVersionTag(cwd).replace(/^v/, "");
+		} catch {
+			throw new Error("No version tags found. Create a tag first (e.g., git tag v0.1.0)");
+		}
+	}
+	/**
+	* Creates a new annotated Git tag for the given version.
+	*
+	* @param version - Version string to tag.
+	* @param cwd - Project directory containing the Git repository.
+	*/
+	setVersion(version, cwd) {
+		execFileSync("git", [
+			"tag",
+			"-a",
+			`${this.detectPrefix(cwd)}${version}`,
+			"-m",
+			`Release ${version}`
+		], {
+			cwd,
+			stdio: [
+				"pipe",
+				"pipe",
+				"ignore"
+			]
+		});
+	}
+	/** Try version-like tag patterns, fall back to any tag. */
+	describeVersionTag(cwd) {
+		try {
+			return execFileSync("git", [
+				"describe",
+				"--tags",
+				"--abbrev=0",
+				"--match",
+				"v[0-9]*"
+			], {
+				cwd,
+				encoding: "utf-8",
+				stdio: [
+					"pipe",
+					"pipe",
+					"ignore"
+				]
+			}).trim();
+		} catch {}
+		try {
+			return execFileSync("git", [
+				"describe",
+				"--tags",
+				"--abbrev=0",
+				"--match",
+				"[0-9]*"
+			], {
+				cwd,
+				encoding: "utf-8",
+				stdio: [
+					"pipe",
+					"pipe",
+					"ignore"
+				]
+			}).trim();
+		} catch {
+			throw new Error("No version tags found");
+		}
+	}
+	/** Detect whether existing tags use a `v` prefix or not. */
+	detectPrefix(cwd) {
+		try {
+			return this.describeVersionTag(cwd).startsWith("v") ? "v" : "";
+		} catch {
+			return "v";
+		}
+	}
+};
+//#endregion
+//#region src/sources/utils.ts
+/**
+* Shared utilities for version source providers.
+*
+* @packageDocumentation
+*/
+/**
+* Traverses a nested object using a dotted key path.
+*
+* @remarks
+* Walks each segment of the dotted path in order, returning `undefined` as
+* soon as a missing or non-object segment is encountered.
+*
+* @param obj - Object to traverse.
+* @param dotPath - Dot-separated key path (e.g. `'package.version'`).
+* @returns The value at the path, or `undefined` if any segment is missing.
+*
+* @example
+* ```ts
+* import { getNestedValue } from './utils';
+*
+* const obj = { package: { version: '1.0.0' } };
+* const version = getNestedValue(obj, 'package.version'); // '1.0.0'
+* ```
+*
+* @public
+* @since 0.3.0
+*/
+function getNestedValue(obj, dotPath) {
+	let current = obj;
+	for (const key of dotPath.split(".")) {
+		if (current === null || typeof current !== "object") return;
+		current = current[key];
+	}
+	return current;
+}
+/**
+* Sets a value at a dotted key path, throwing if intermediate segments are missing.
+*
+* @remarks
+* Traverses each intermediate segment and throws when a segment is missing or
+* not an object. The final key is created or overwritten.
+*
+* @param obj - Object to mutate.
+* @param dotPath - Dot-separated key path.
+* @param value - Value to set at the final key.
+*
+* @example
+* ```ts
+* import { setNestedValue } from './utils';
+*
+* const obj = { package: { version: '1.0.0' } };
+* setNestedValue(obj, 'package.version', '2.0.0');
+* ```
+*
+* @public
+* @since 0.3.0
+*/
+function setNestedValue(obj, dotPath, value) {
+	const keys = dotPath.split(".");
+	let current = obj;
+	for (let i = 0; i < keys.length - 1; i++) {
+		const next = current[keys[i]];
+		if (typeof next !== "object" || next === null) throw new Error(`Missing intermediate key '${keys.slice(0, i + 1).join(".")}' in manifest`);
+		current = next;
+	}
+	current[keys[keys.length - 1]] = value;
+}
+/**
+* Escapes special regex characters in a string for safe use in `new RegExp()`.
+*
+* @remarks
+* Prefixes every character that has special meaning in a regular expression
+* with a backslash so the resulting string matches literally.
+*
+* @param value - Raw string to escape.
+* @returns The escaped string safe for embedding in a `RegExp` constructor.
+*
+* @example
+* ```ts
+* import { escapeRegExp } from './utils';
+*
+* const escaped = escapeRegExp('file.txt'); // 'file\\.txt'
+* ```
+*
+* @public
+* @since 0.3.0
+*/
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region src/sources/json.ts
+/**
+* JSON-based version source provider for package.json and composer.json.
+*
+* @packageDocumentation
+*/
+/**
+* Reads and writes version strings from JSON manifest files.
+*
+* @remarks
+* Supports dotted key paths for nested version fields and preserves the
+* original indentation style when writing back to disk.
+*
+* @public
+* @since 0.3.0
+*/
+var JsonVersionSource = class {
+	/** Human-readable provider name. */
+	name;
+	/** Filename of the JSON manifest (e.g. `'package.json'`). */
+	manifestFile;
+	/** Dotted key path to the version field within the JSON document. */
+	versionPath;
+	/**
+	* Creates a new JSON version source.
+	*
+	* @param manifestFile - JSON manifest filename.
+	* @param versionPath - Dotted key path to the version field.
+	*/
+	constructor(manifestFile = "package.json", versionPath = "version") {
+		this.name = manifestFile;
+		this.manifestFile = manifestFile;
+		this.versionPath = versionPath;
+	}
+	/**
+	* Returns `true` when the manifest file exists in `cwd`.
+	*
+	* @param cwd - Project directory to check.
+	* @returns Whether the manifest file exists.
+	*/
+	exists(cwd) {
+		return fs.existsSync(path.join(cwd, this.manifestFile));
+	}
+	/**
+	* Reads the version string from the JSON manifest.
+	*
+	* @param cwd - Project directory containing the manifest.
+	* @returns The version string extracted from the manifest.
+	*/
+	getVersion(cwd) {
+		const filePath = path.join(cwd, this.manifestFile);
+		if (!fs.existsSync(filePath)) throw new Error(`${this.manifestFile} not found in ${cwd}`);
+		const version = getNestedValue(JSON.parse(fs.readFileSync(filePath, "utf-8")), this.versionPath);
+		if (typeof version !== "string" || version.length === 0) throw new Error(`No version field in ${this.manifestFile}`);
+		return version;
+	}
+	/**
+	* Writes a version string to the JSON manifest, preserving indentation.
+	*
+	* @param version - Version string to write.
+	* @param cwd - Project directory containing the manifest.
+	*/
+	setVersion(version, cwd) {
+		const filePath = path.join(cwd, this.manifestFile);
+		if (!fs.existsSync(filePath)) throw new Error(`${this.manifestFile} not found in ${cwd}`);
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const indent = raw.match(/^(\s+)"/m)?.[1]?.length ?? 2;
+		const content = JSON.parse(raw);
+		setNestedValue(content, this.versionPath, version);
+		fs.writeFileSync(filePath, `${JSON.stringify(content, null, indent)}\n`, "utf-8");
+	}
+};
+//#endregion
+//#region src/sources/regex.ts
+/**
+* Regex-based version source for source-code manifests.
+*
+* Handles gemspec, mix.exs, setup.py, build.gradle, etc.
+*
+* @packageDocumentation
+*/
+/**
+* Reads and writes version strings using regex extraction from source files.
+*
+* @remarks
+* Capture group 1 of the provided regex must match the version string.
+* Uses position-based replacement to avoid wrong-match corruption when
+* writing back to disk.
+*
+* @public
+* @since 0.3.0
+*/
+var RegexVersionSource = class {
+	/** Human-readable provider name. */
+	name;
+	/** Filename of the source manifest (e.g. `'setup.py'`). */
+	manifestFile;
+	/** Compiled regex used to locate the version string. */
+	versionRegex;
+	/**
+	* Creates a new regex version source.
+	*
+	* @param manifestFile - Source manifest filename.
+	* @param versionRegex - Regex string with at least one capture group for the version.
+	*/
+	constructor(manifestFile, versionRegex) {
+		this.name = manifestFile;
+		this.manifestFile = manifestFile;
+		try {
+			this.versionRegex = new RegExp(versionRegex, "m");
+		} catch (err) {
+			throw new Error(`Invalid version regex for ${manifestFile}: ${err.message}`);
+		}
+		if (!/\((?!\?)/.test(versionRegex)) throw new Error(`Version regex for ${manifestFile} must contain at least one capture group`);
+	}
+	/**
+	* Returns `true` when the manifest file exists in `cwd`.
+	*
+	* @param cwd - Project directory to check.
+	* @returns Whether the manifest file exists.
+	*/
+	exists(cwd) {
+		return fs.existsSync(path.join(cwd, this.manifestFile));
+	}
+	/**
+	* Reads the version string from the source manifest using regex extraction.
+	*
+	* @param cwd - Project directory containing the manifest.
+	* @returns The version string captured by group 1 of the regex.
+	*/
+	getVersion(cwd) {
+		const filePath = path.join(cwd, this.manifestFile);
+		if (!fs.existsSync(filePath)) throw new Error(`${this.manifestFile} not found in ${cwd}`);
+		const match = fs.readFileSync(filePath, "utf-8").match(this.versionRegex);
+		if (!match?.[1]) throw new Error(`No version match found in ${this.manifestFile}`);
+		return match[1];
+	}
+	/**
+	* Writes a version string to the source manifest using position-based replacement.
+	*
+	* @param version - Version string to write.
+	* @param cwd - Project directory containing the manifest.
+	*/
+	setVersion(version, cwd) {
+		const filePath = path.join(cwd, this.manifestFile);
+		if (!fs.existsSync(filePath)) throw new Error(`${this.manifestFile} not found in ${cwd}`);
+		const content = fs.readFileSync(filePath, "utf-8");
+		const match = this.versionRegex.exec(content);
+		if (!match || match.index === void 0) throw new Error(`No version match found in ${this.manifestFile}`);
+		const captureStart = match.index + match[0].indexOf(match[1]);
+		const captureEnd = captureStart + match[1].length;
+		const updated = content.slice(0, captureStart) + version + content.slice(captureEnd);
+		fs.writeFileSync(filePath, updated, "utf-8");
+	}
+};
+//#endregion
+//#region src/sources/toml.ts
+/**
+* TOML-based version source provider for Cargo.toml and pyproject.toml.
+*
+* @packageDocumentation
+*/
+/**
+* Reads and writes version strings from TOML manifest files.
+*
+* @remarks
+* Uses targeted regex replacement for writes to preserve file formatting,
+* comments, and whitespace. Supports standard section headers, dotted keys,
+* and inline table syntax.
+*
+* @public
+* @since 0.3.0
+*/
+var TomlVersionSource = class {
+	/** Human-readable provider name. */
+	name;
+	/** Filename of the TOML manifest (e.g. `'Cargo.toml'`). */
+	manifestFile;
+	/** Dotted key path to the version field within the TOML document. */
+	versionPath;
+	/**
+	* Creates a new TOML version source.
+	*
+	* @param manifestFile - TOML manifest filename.
+	* @param versionPath - Dotted key path to the version field.
+	*/
+	constructor(manifestFile = "Cargo.toml", versionPath = "package.version") {
+		this.name = manifestFile;
+		this.manifestFile = manifestFile;
+		this.versionPath = versionPath;
+	}
+	/**
+	* Returns `true` when the manifest file exists in `cwd`.
+	*
+	* @param cwd - Project directory to check.
+	* @returns Whether the manifest file exists.
+	*/
+	exists(cwd) {
+		return fs.existsSync(path.join(cwd, this.manifestFile));
+	}
+	/**
+	* Reads the version string from the TOML manifest.
+	*
+	* @param cwd - Project directory containing the manifest.
+	* @returns The version string extracted from the manifest.
+	*/
+	getVersion(cwd) {
+		const filePath = path.join(cwd, this.manifestFile);
+		if (!fs.existsSync(filePath)) throw new Error(`${this.manifestFile} not found in ${cwd}`);
+		const version = getNestedValue(parse(fs.readFileSync(filePath, "utf-8")), this.versionPath);
+		if (typeof version !== "string" || version.length === 0) throw new Error(`No version field at '${this.versionPath}' in ${this.manifestFile}`);
+		return version;
+	}
+	/**
+	* Writes a version string to the TOML manifest, preserving formatting.
+	*
+	* @param version - Version string to write.
+	* @param cwd - Project directory containing the manifest.
+	*/
+	setVersion(version, cwd) {
+		const filePath = path.join(cwd, this.manifestFile);
+		if (!fs.existsSync(filePath)) throw new Error(`${this.manifestFile} not found in ${cwd}`);
+		const content = fs.readFileSync(filePath, "utf-8");
+		const updated = replaceTomlVersion(content, this.getSectionKey(), version);
+		if (updated === content) throw new Error(`Could not find version field to update in ${this.manifestFile}`);
+		fs.writeFileSync(filePath, updated, "utf-8");
+	}
+	/**
+	* Splits the dotted version path into a TOML section name and key name.
+	*
+	* @returns An object with `section` and `key` components.
+	*/
+	getSectionKey() {
+		const parts = this.versionPath.split(".");
+		if (parts.length === 1) return {
+			section: "",
+			key: parts[0]
+		};
+		return {
+			section: parts.slice(0, -1).join("."),
+			key: parts[parts.length - 1]
+		};
+	}
+};
+/**
+* Replace a version value within a TOML file, preserving formatting.
+*
+* Tries three patterns in order:
+* 1. [section] header + key = "value" line (standard)
+* 2. Dotted key syntax: section.key = "value" (M-004)
+* 3. Inline table: section = { ..., key = "value", ... } (M-010)
+*/
+function replaceTomlVersion(content, target, newVersion) {
+	const result = replaceInSection(content, target, newVersion);
+	if (result !== content) return result;
+	if (target.section) {
+		const dottedRegex = new RegExp(`^(\\s*${escapeRegExp(target.section)}\\.${escapeRegExp(target.key)}\\s*=\\s*)(["'])([^"']*)(\\2)`, "m");
+		const dottedResult = content.replace(dottedRegex, `$1$2${newVersion}$4`);
+		if (dottedResult !== content) return dottedResult;
+	}
+	if (target.section) {
+		const inlineRegex = new RegExp(`^(\\s*${escapeRegExp(target.section)}\\s*=\\s*\\{[^}]*${escapeRegExp(target.key)}\\s*=\\s*)(["'])([^"']*)(\\2)`, "m");
+		const inlineResult = content.replace(inlineRegex, `$1$2${newVersion}$4`);
+		if (inlineResult !== content) return inlineResult;
+	}
+	return content;
+}
+/** Standard section-header-based replacement. */
+function replaceInSection(content, target, newVersion) {
+	const lines = content.split("\n");
+	const sectionHeader = target.section ? `[${target.section}]` : null;
+	let inSection = sectionHeader === null;
+	const versionRegex = new RegExp(`^(\\s*${escapeRegExp(target.key)}\\s*=\\s*)(["'])([^"']*)(\\2)`);
+	for (let i = 0; i < lines.length; i++) {
+		const trimmed = lines[i].trim();
+		if (sectionHeader !== null) {
+			if (trimmed === sectionHeader) {
+				inSection = true;
+				continue;
+			}
+			if (inSection && trimmed.startsWith("[") && trimmed !== sectionHeader) {
+				inSection = false;
+				continue;
+			}
+		}
+		if (inSection) {
+			if (lines[i].match(versionRegex)) {
+				lines[i] = lines[i].replace(versionRegex, `$1$2${newVersion}$4`);
+				return lines.join("\n");
+			}
+		}
+	}
+	return content;
+}
+//#endregion
+//#region src/sources/version-file.ts
+/**
+* Plain text VERSION file provider.
+*
+* @packageDocumentation
+*/
+/**
+* Reads and writes version strings from a plain text VERSION file.
+*
+* @remarks
+* The file is expected to contain only the version string, optionally
+* followed by a trailing newline. Binary files and empty files are
+* rejected with a descriptive error.
+*
+* @public
+* @since 0.3.0
+*/
+var VersionFileSource = class {
+	/** Human-readable provider name. */
+	name;
+	/** Filename of the version file (e.g. `'VERSION'`). */
+	manifestFile;
+	/**
+	* Creates a new plain text version file source.
+	*
+	* @param manifestFile - Version filename.
+	*/
+	constructor(manifestFile = "VERSION") {
+		this.name = manifestFile;
+		this.manifestFile = manifestFile;
+	}
+	/**
+	* Returns `true` when the version file exists in `cwd`.
+	*
+	* @param cwd - Project directory to check.
+	* @returns Whether the version file exists.
+	*/
+	exists(cwd) {
+		return fs.existsSync(path.join(cwd, this.manifestFile));
+	}
+	/**
+	* Reads the version string from the plain text version file.
+	*
+	* @param cwd - Project directory containing the version file.
+	* @returns The version string from the first line of the file.
+	*/
+	getVersion(cwd) {
+		const filePath = path.join(cwd, this.manifestFile);
+		if (!fs.existsSync(filePath)) throw new Error(`${this.manifestFile} not found in ${cwd}`);
+		const raw = fs.readFileSync(filePath, "utf-8");
+		if (raw.includes("\0")) throw new Error(`${this.manifestFile} appears to be a binary file`);
+		const version = raw.split("\n")[0].trim();
+		if (version.length === 0) throw new Error(`${this.manifestFile} is empty`);
+		return version;
+	}
+	/**
+	* Writes a version string to the plain text version file.
+	*
+	* @param version - Version string to write.
+	* @param cwd - Project directory containing the version file.
+	*/
+	setVersion(version, cwd) {
+		const filePath = path.join(cwd, this.manifestFile);
+		if (!fs.existsSync(filePath)) throw new Error(`${this.manifestFile} not found in ${cwd}`);
+		fs.writeFileSync(filePath, `${version}\n`, "utf-8");
+	}
+};
+//#endregion
+//#region src/sources/yaml.ts
+/**
+* YAML-based version source provider for pubspec.yaml and similar manifests.
+*
+* @packageDocumentation
+*/
+/**
+* Reads and writes version strings from YAML manifest files.
+*
+* @remarks
+* Supports dotted key paths (e.g. `'flutter.version'`) for nested values.
+* Uses targeted regex replacement for writes to preserve comments and formatting.
+*
+* @public
+* @since 0.3.0
+*/
+var YamlVersionSource = class {
+	/** Human-readable provider name. */
+	name;
+	/** Filename of the YAML manifest (e.g. `'pubspec.yaml'`). */
+	manifestFile;
+	/** Dotted key path to the version field within the YAML document. */
+	versionKey;
+	/**
+	* Creates a new YAML version source.
+	*
+	* @param manifestFile - YAML manifest filename.
+	* @param versionKey - Dotted key path to the version field.
+	*/
+	constructor(manifestFile = "pubspec.yaml", versionKey = "version") {
+		this.name = manifestFile;
+		this.manifestFile = manifestFile;
+		this.versionKey = versionKey;
+	}
+	/**
+	* Returns `true` when the manifest file exists in `cwd`.
+	*
+	* @param cwd - Project directory to check.
+	* @returns Whether the manifest file exists.
+	*/
+	exists(cwd) {
+		return fs.existsSync(path.join(cwd, this.manifestFile));
+	}
+	/**
+	* Reads the version string from the YAML manifest.
+	*
+	* @param cwd - Project directory containing the manifest.
+	* @returns The version string extracted from the manifest.
+	*/
+	getVersion(cwd) {
+		const filePath = path.join(cwd, this.manifestFile);
+		if (!fs.existsSync(filePath)) throw new Error(`${this.manifestFile} not found in ${cwd}`);
+		const content = fs.readFileSync(filePath, "utf-8");
+		const parsed = yaml.load(content);
+		if (!parsed || typeof parsed !== "object") throw new Error(`Failed to parse ${this.manifestFile}`);
+		const version = getNestedValue(parsed, this.versionKey);
+		if (typeof version !== "string" || version.length === 0) {
+			if (typeof version === "number") return String(version);
+			throw new Error(`No version field in ${this.manifestFile}`);
+		}
+		return version;
+	}
+	/**
+	* Writes a version string to the YAML manifest, preserving formatting.
+	*
+	* @param version - Version string to write.
+	* @param cwd - Project directory containing the manifest.
+	*/
+	setVersion(version, cwd) {
+		const filePath = path.join(cwd, this.manifestFile);
+		if (!fs.existsSync(filePath)) throw new Error(`${this.manifestFile} not found in ${cwd}`);
+		const keyParts = this.versionKey.split(".");
+		const leafKey = keyParts[keyParts.length - 1];
+		const content = fs.readFileSync(filePath, "utf-8");
+		const regex = new RegExp(`^(\\s*${escapeRegExp(leafKey)}:\\s*)(["']?)(.+?)\\2\\s*$`, "m");
+		const updated = content.replace(regex, `$1$2${version}$2`);
+		if (updated === content) throw new Error(`Could not find version field to update in ${this.manifestFile}`);
+		fs.writeFileSync(filePath, updated, "utf-8");
+	}
+};
+//#endregion
+//#region src/sources/resolve.ts
+/**
+* Version source auto-detection and resolution.
+*
+* @packageDocumentation
+*/
+/** Valid manifest source types for config validation (H-006). */
+var VALID_SOURCES = new Set([
+	"auto",
+	"package.json",
+	"composer.json",
+	"Cargo.toml",
+	"pyproject.toml",
+	"pubspec.yaml",
+	"pom.xml",
+	"VERSION",
+	"git-tag",
+	"custom"
+]);
+/**
+* Known manifest detection entries, ordered by priority.
+*
+* When `source` is `'auto'`, the first entry whose file exists wins.
+*/
+var DETECTION_TABLE = [
+	{
+		file: "package.json",
+		source: "package.json",
+		factory: () => new JsonVersionSource("package.json", "version")
+	},
+	{
+		file: "Cargo.toml",
+		source: "Cargo.toml",
+		factory: () => new TomlVersionSource("Cargo.toml", "package.version")
+	},
+	{
+		file: "pyproject.toml",
+		source: "pyproject.toml",
+		factory: () => new TomlVersionSource("pyproject.toml", "project.version")
+	},
+	{
+		file: "pubspec.yaml",
+		source: "pubspec.yaml",
+		factory: () => new YamlVersionSource("pubspec.yaml", "version")
+	},
+	{
+		file: "composer.json",
+		source: "composer.json",
+		factory: () => new JsonVersionSource("composer.json", "version")
+	},
+	{
+		file: "pom.xml",
+		source: "pom.xml",
+		factory: () => new RegexVersionSource("pom.xml", "<project[^>]*>[\\s\\S]*?<version>([^<]+)</version>")
+	},
+	{
+		file: "VERSION",
+		source: "VERSION",
+		factory: () => new VersionFileSource("VERSION")
+	}
+];
+/**
+* Validates that a file path does not escape the project directory (C-002).
+*/
+function assertPathContained(manifestFile, cwd) {
+	const resolved = path.resolve(cwd, manifestFile);
+	const root = path.resolve(cwd);
+	if (!resolved.startsWith(`${root}${path.sep}`) && resolved !== root) throw new Error(`Manifest path "${manifestFile}" resolves outside the project directory`);
+}
+/**
+* Creates a provider for a specific manifest source type.
+*/
+function createProvider(source, config, cwd) {
+	if (!VALID_SOURCES.has(source)) throw new Error(`Invalid manifest source "${source}". Valid sources: ${[...VALID_SOURCES].join(", ")}`);
+	switch (source) {
+		case "package.json": return new JsonVersionSource("package.json", config.path ?? "version");
+		case "composer.json": return new JsonVersionSource("composer.json", config.path ?? "version");
+		case "Cargo.toml": return new TomlVersionSource("Cargo.toml", config.path ?? "package.version");
+		case "pyproject.toml": return new TomlVersionSource("pyproject.toml", config.path ?? "project.version");
+		case "pubspec.yaml": return new YamlVersionSource("pubspec.yaml", config.path ?? "version");
+		case "pom.xml": return new RegexVersionSource("pom.xml", config.regex ?? "<project[^>]*>[\\s\\S]*?<version>([^<]+)</version>");
+		case "VERSION": return new VersionFileSource(config.path ?? "VERSION");
+		case "git-tag": return new GitTagSource();
+		case "custom":
+			if (!config.regex) throw new Error("Custom manifest source requires a 'regex' field in manifest config");
+			if (!config.path) throw new Error("Custom manifest source requires a 'path' field (manifest filename) in manifest config");
+			assertPathContained(config.path, cwd);
+			return new RegexVersionSource(config.path, config.regex);
+		default: throw new Error(`Unknown manifest source: ${source}`);
+	}
+}
+/**
+* Resolves the version source provider for a project.
+*
+* @remarks
+* When `source` is `'auto'`, scans the project directory for known manifest
+* files and returns the first match. Throws with helpful guidance if no
+* supported manifest is found.
+*
+* @param config - Manifest configuration from `.versionguard.yml`.
+* @param cwd - Project directory to scan.
+* @returns The resolved version source provider.
+*
+* @example
+* ```ts
+* import { resolveVersionSource } from './resolve';
+*
+* const provider = resolveVersionSource({ source: 'auto' }, process.cwd());
+* const version = provider.getVersion(process.cwd());
+* ```
+*
+* @public
+* @since 0.3.0
+*/
+function resolveVersionSource(config, cwd = process.cwd()) {
+	if (config.source !== "auto") return createProvider(config.source, config, cwd);
+	for (const entry of DETECTION_TABLE) {
+		const provider = entry.factory();
+		if (provider.exists(cwd)) return provider;
+	}
+	const supported = DETECTION_TABLE.map((e) => e.file).join(", ");
+	throw new Error(`No supported manifest file found in ${cwd}. Looked for: ${supported}. Set manifest.source explicitly in .versionguard.yml or create a supported manifest file.`);
+}
+/**
+* Detects all manifest files present in a project directory.
+*
+* @remarks
+* Useful for polyglot projects that may have multiple version sources.
+* Scans the detection table in priority order and returns all matches.
+*
+* @param cwd - Project directory to scan.
+* @returns Array of detected manifest source types.
+*
+* @example
+* ```ts
+* import { detectManifests } from './resolve';
+*
+* const manifests = detectManifests(process.cwd());
+* // ['package.json', 'Cargo.toml']
+* ```
+*
+* @public
+* @since 0.3.0
+*/
+function detectManifests(cwd = process.cwd()) {
+	const detected = [];
+	for (const entry of DETECTION_TABLE) if (entry.factory().exists(cwd)) detected.push(entry.source);
+	return detected;
+}
+//#endregion
+//#region src/project.ts
+/**
+* Gets the `package.json` path for a project directory.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This is a convenience helper used by the package read and write helpers.
+*
+* @param cwd - Project directory containing `package.json`.
+* @returns The resolved `package.json` path.
+* @example
+* ```ts
+* import { getPackageJsonPath } from 'versionguard';
+*
+* const packagePath = getPackageJsonPath(process.cwd());
+* ```
+*/
+function getPackageJsonPath(cwd = process.cwd()) {
+	return path.join(cwd, "package.json");
+}
+/**
+* Reads and parses a project's `package.json` file.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* An error is thrown when `package.json` does not exist in the requested
+* directory.
+*
+* @param cwd - Project directory containing `package.json`.
+* @returns The parsed `package.json` document.
+* @example
+* ```ts
+* import { readPackageJson } from 'versionguard';
+*
+* const pkg = readPackageJson(process.cwd());
+* ```
+*/
+function readPackageJson(cwd = process.cwd()) {
+	const packagePath = getPackageJsonPath(cwd);
+	if (!fs.existsSync(packagePath)) throw new Error(`package.json not found in ${cwd}`);
+	return JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+}
+/**
+* Writes a `package.json` document back to disk.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* Output is formatted with two-space indentation and always ends with a
+* trailing newline.
+*
+* @param pkg - Parsed `package.json` data to write.
+* @param cwd - Project directory containing `package.json`.
+* @example
+* ```ts
+* import { readPackageJson, writePackageJson } from 'versionguard';
+*
+* const pkg = readPackageJson(process.cwd());
+* writePackageJson(pkg, process.cwd());
+* ```
+*/
+function writePackageJson(pkg, cwd = process.cwd()) {
+	fs.writeFileSync(getPackageJsonPath(cwd), `${JSON.stringify(pkg, null, 2)}\n`, "utf-8");
+}
+/**
+* Gets the version string from the project manifest.
+*
+* When a `manifest` config is provided, uses the configured version source
+* provider (auto-detection or explicit). Falls back to `package.json` for
+* backwards compatibility when no config is provided.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This throws when the manifest file does not exist or does not contain
+* a version field.
+*
+* @param cwd - Project directory containing the manifest.
+* @param manifest - Optional manifest configuration for language-agnostic support.
+* @returns The project version string.
+* @example
+* ```ts
+* import { getPackageVersion } from 'versionguard';
+*
+* // Read from package.json (legacy fallback)
+* const version = getPackageVersion(process.cwd());
+*
+* // Read from a configured manifest source
+* const versionAlt = getPackageVersion(process.cwd(), { source: 'Cargo.toml' });
+* ```
+*/
+function getPackageVersion(cwd = process.cwd(), manifest) {
+	if (manifest) return resolveVersionSource(manifest, cwd).getVersion(cwd);
+	const pkg = readPackageJson(cwd);
+	if (typeof pkg.version !== "string" || pkg.version.length === 0) throw new Error("No version field in package.json");
+	return pkg.version;
+}
+/**
+* Sets the version field in the project manifest.
+*
+* When a `manifest` config is provided, uses the configured version source
+* provider. Falls back to `package.json` for backwards compatibility when
+* no config is provided.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* The existing document is read, the version field is replaced, and the
+* file is written back to disk.
+*
+* @param version - Version string to persist.
+* @param cwd - Project directory containing the manifest.
+* @param manifest - Optional manifest configuration for language-agnostic support.
+* @example
+* ```ts
+* import { setPackageVersion } from 'versionguard';
+*
+* // Write to package.json (legacy fallback)
+* setPackageVersion('1.2.3', process.cwd());
+*
+* // Write to a configured manifest source
+* setPackageVersion('1.2.3', process.cwd(), { source: 'Cargo.toml' });
+* ```
+*/
+function setPackageVersion(version, cwd = process.cwd(), manifest) {
+	if (manifest) {
+		resolveVersionSource(manifest, cwd).setVersion(version, cwd);
+		return;
+	}
+	const pkg = readPackageJson(cwd);
+	pkg.version = version;
+	writePackageJson(pkg, cwd);
+}
+/**
+* Resolves the version source provider for a project.
+*
+* @remarks
+* Delegates to `resolveVersionSource` to create the appropriate provider
+* for the configured manifest type. Use this when you need direct access
+* to the provider's `exists`, `getVersion`, and `setVersion` methods.
+*
+* @param manifest - Manifest configuration.
+* @param cwd - Project directory.
+* @returns The resolved provider instance.
+*
+* @example
+* ```ts
+* import { getVersionSource } from 'versionguard';
+*
+* const source = getVersionSource({ source: 'package.json' }, process.cwd());
+* const version = source.getVersion(process.cwd());
+* ```
+*
+* @public
+* @since 0.3.0
+*/
+function getVersionSource(manifest, cwd = process.cwd()) {
+	return resolveVersionSource(manifest, cwd);
+}
+//#endregion
+//#region src/semver.ts
+/**
+* Semantic version parsing, validation, comparison, and increment helpers.
+*
+* @packageDocumentation
+*/
+var semver_exports = /* @__PURE__ */ __exportAll({
+	compare: () => compare,
+	eq: () => eq,
+	format: () => format,
+	gt: () => gt,
+	increment: () => increment,
+	lt: () => lt,
+	parse: () => parse$1,
+	validate: () => validate$1
+});
+var SEMVER_REGEX = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+/**
+* 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
+*/
+function parse$1(version) {
+	const match = version.match(SEMVER_REGEX);
+	if (!match) return null;
+	return {
+		major: Number.parseInt(match[1], 10),
+		minor: Number.parseInt(match[2], 10),
+		patch: Number.parseInt(match[3], 10),
+		prerelease: match[4] ? match[4].split(".") : [],
+		build: match[5] ? match[5].split(".") : [],
+		raw: version
+	};
+}
+function getStructuralErrors(version) {
+	const errors = [];
+	if (version.startsWith("v")) {
+		errors.push({
+			message: `Version should not start with 'v': ${version}`,
+			severity: "error"
+		});
+		return errors;
+	}
+	const segments = version.split(/[+-]/, 1)[0].split(".");
+	if (segments.length === 3) {
+		const leadingZeroSegment = segments.find((segment) => /^0\d+$/.test(segment));
+		if (leadingZeroSegment) {
+			errors.push({
+				message: `Invalid SemVer: numeric segment "${leadingZeroSegment}" has a leading zero`,
+				severity: "error"
+			});
+			return errors;
+		}
+	}
+	const prerelease = version.match(/-([^+]+)/)?.[1];
+	if (prerelease) {
+		const invalidPrerelease = prerelease.split(".").find((segment) => /^0\d+$/.test(segment));
+		if (invalidPrerelease) {
+			errors.push({
+				message: `Invalid SemVer: prerelease identifier "${invalidPrerelease}" has a leading zero`,
+				severity: "error"
+			});
+			return errors;
+		}
+	}
+	errors.push({
+		message: `Invalid SemVer format: "${version}". Expected MAJOR.MINOR.PATCH[-prerelease][+build].`,
+		severity: "error"
+	});
+	return errors;
+}
+/**
+* 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.
+*
+* When a {@link SemVerConfig} is provided, additional policy checks are applied
+* (v-prefix tolerance, build-metadata restrictions, prerelease requirements).
+* When {@link SchemeRules} are provided, the prerelease tag is validated against
+* the allowed modifiers list — the same logic CalVer uses for its modifiers.
+*
+* @param version - Version string to validate.
+* @param semverConfig - Optional SemVer-specific configuration.
+* @param schemeRules - Optional scheme rules for modifier validation.
+* @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
+*/
+function validate$1(version, semverConfig, schemeRules) {
+	let input = version;
+	if (input.startsWith("v") || input.startsWith("V")) {
+		if (semverConfig?.allowVPrefix) input = input.slice(1);
+	}
+	const parsed = parse$1(input);
+	if (!parsed) return {
+		valid: false,
+		errors: getStructuralErrors(version)
+	};
+	const errors = [];
+	if (semverConfig && !semverConfig.allowBuildMetadata && parsed.build.length > 0) errors.push({
+		message: `Build metadata is not allowed: "${parsed.build.join(".")}"`,
+		severity: "error"
+	});
+	if (semverConfig?.requirePrerelease && parsed.prerelease.length === 0) errors.push({
+		message: "A prerelease label is required (e.g., 1.2.3-alpha.1)",
+		severity: "error"
+	});
+	if (parsed.prerelease.length > 0) {
+		const modifierError = validateModifier(parsed.prerelease[0], schemeRules);
+		if (modifierError) errors.push(modifierError);
+	}
+	return {
+		valid: errors.filter((e) => e.severity === "error").length === 0,
+		errors,
+		version: {
+			type: "semver",
+			version: parsed
+		}
+	};
+}
+/**
+* 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
+*/
+function compare(a, b) {
+	const left = parse$1(a);
+	const right = parse$1(b);
+	if (!left || !right) throw new Error(`Invalid SemVer comparison between "${a}" and "${b}"`);
+	for (const key of [
+		"major",
+		"minor",
+		"patch"
+	]) if (left[key] !== right[key]) return left[key] > right[key] ? 1 : -1;
+	const leftHasPrerelease = left.prerelease.length > 0;
+	const rightHasPrerelease = right.prerelease.length > 0;
+	if (leftHasPrerelease && !rightHasPrerelease) return -1;
+	if (!leftHasPrerelease && rightHasPrerelease) return 1;
+	const length = Math.max(left.prerelease.length, right.prerelease.length);
+	for (let index = 0; index < length; index += 1) {
+		const leftValue = left.prerelease[index];
+		const rightValue = right.prerelease[index];
+		if (leftValue === void 0) return -1;
+		if (rightValue === void 0) return 1;
+		const leftNumeric = /^\d+$/.test(leftValue) ? Number.parseInt(leftValue, 10) : null;
+		const rightNumeric = /^\d+$/.test(rightValue) ? Number.parseInt(rightValue, 10) : null;
+		if (leftNumeric !== null && rightNumeric !== null) {
+			if (leftNumeric !== rightNumeric) return leftNumeric > rightNumeric ? 1 : -1;
+			continue;
+		}
+		if (leftNumeric !== null) return -1;
+		if (rightNumeric !== null) return 1;
+		if (leftValue !== rightValue) return leftValue > rightValue ? 1 : -1;
+	}
+	return 0;
+}
+/**
+* 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
+*/
+function gt(a, b) {
+	return compare(a, b) > 0;
+}
+/**
+* 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
+*/
+function lt(a, b) {
+	return compare(a, b) < 0;
+}
+/**
+* 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
+*/
+function eq(a, b) {
+	return compare(a, b) === 0;
+}
+/**
+* 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
+*/
+function increment(version, release, prerelease) {
+	const parsed = parse$1(version);
+	if (!parsed) throw new Error(`Invalid SemVer version: ${version}`);
+	if (release === "major") return `${parsed.major + 1}.0.0${prerelease ? `-${prerelease}` : ""}`;
+	if (release === "minor") return `${parsed.major}.${parsed.minor + 1}.0${prerelease ? `-${prerelease}` : ""}`;
+	return `${parsed.major}.${parsed.minor}.${parsed.patch + 1}${prerelease ? `-${prerelease}` : ""}`;
+}
+/**
+* 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
+*/
+function format(version) {
+	let output = `${version.major}.${version.minor}.${version.patch}`;
+	if (version.prerelease.length > 0) output += `-${version.prerelease.join(".")}`;
+	if (version.build.length > 0) output += `+${version.build.join(".")}`;
+	return output;
+}
+//#endregion
+//#region src/sync.ts
+function resolveFiles(patterns, cwd, ignore = []) {
+	return [...new Set(patterns.flatMap((pattern) => globSync(pattern, {
+		cwd,
+		absolute: true,
+		ignore
+	})))].sort();
+}
+function getLineNumber(content, offset) {
+	return content.slice(0, offset).split("\n").length;
+}
+function extractVersion(groups) {
+	return groups[1] ?? groups[0] ?? "";
+}
+function applyTemplate(template, groups, version) {
+	return template.replace(/\$(\d+)|\{\{version\}\}/g, (match, groupIndex) => {
+		if (match === "{{version}}") return version;
+		return groups[Number.parseInt(groupIndex ?? "0", 10) - 1] ?? "";
+	});
+}
+function stringifyCapture(value) {
+	return typeof value === "string" ? value : "";
+}
+/**
+* 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());
+* ```
+*/
+function syncVersion(version, config, cwd = process.cwd()) {
+	return resolveFiles(config.files, cwd).map((filePath) => syncFile(filePath, version, config.patterns));
+}
+/**
+* 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);
+* ```
+*/
+function syncFile(filePath, version, patterns) {
+	const original = fs.readFileSync(filePath, "utf-8");
+	let updatedContent = original;
+	const changes = [];
+	for (const pattern of patterns) {
+		const regex = new RegExp(pattern.regex, "gm");
+		updatedContent = updatedContent.replace(regex, (match, ...args) => {
+			const offsetIndex = typeof args.at(-1) === "object" && args.at(-1) !== null ? -3 : -2;
+			const offset = args.at(offsetIndex);
+			const groups = args.slice(0, offsetIndex).map((value) => stringifyCapture(value));
+			const found = extractVersion(groups);
+			if (found === "Unreleased") return match;
+			if (found !== version) changes.push({
+				line: getLineNumber(updatedContent, offset),
+				oldValue: found,
+				newValue: version
+			});
+			return applyTemplate(pattern.template, groups, version) || match;
+		});
+	}
+	const result = {
+		file: filePath,
+		updated: updatedContent !== original,
+		changes
+	};
+	if (result.updated) fs.writeFileSync(filePath, updatedContent, "utf-8");
+	return result;
+}
+/**
+* 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(),
+* );
+* ```
+*/
+function checkHardcodedVersions(expectedVersion, config, ignorePatterns, cwd = process.cwd()) {
+	const mismatches = [];
+	const files = resolveFiles(config.files, cwd, ignorePatterns);
+	for (const filePath of files) {
+		const content = fs.readFileSync(filePath, "utf-8");
+		for (const pattern of config.patterns) {
+			const regex = new RegExp(pattern.regex, "gm");
+			let match = regex.exec(content);
+			while (match) {
+				const found = extractVersion(match.slice(1));
+				if (found !== "Unreleased" && found !== expectedVersion) mismatches.push({
+					file: path.relative(cwd, filePath),
+					line: getLineNumber(content, match.index),
+					found
+				});
+				match = regex.exec(content);
+			}
+		}
+	}
+	return mismatches;
+}
+/** Extensions that are almost certainly binary and should be skipped. */
+var BINARY_EXTENSIONS = new Set([
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".ico",
+	".svg",
+	".woff",
+	".woff2",
+	".ttf",
+	".eot",
+	".otf",
+	".zip",
+	".tar",
+	".gz",
+	".bz2",
+	".7z",
+	".pdf",
+	".exe",
+	".dll",
+	".so",
+	".dylib",
+	".wasm",
+	".mp3",
+	".mp4",
+	".webm",
+	".webp",
+	".avif"
+]);
+/**
+* Scans the entire repository for hardcoded version literals.
+*
+* @public
+* @since 0.8.0
+* @remarks
+* Unlike {@link checkHardcodedVersions}, which only checks files listed in
+* `sync.files`, this function globs the entire repository (respecting
+* `.gitignore` and `ignore` patterns) and applies configurable version-like
+* regex patterns. An allowlist filters out intentional references.
+*
+* @param expectedVersion - Version all matching entries should use.
+* @param scanConfig - Scan configuration with patterns and allowlist.
+* @param ignorePatterns - Glob patterns to exclude while scanning.
+* @param cwd - Project directory used to resolve file globs.
+* @returns A list of detected version mismatches across the repository.
+* @example
+* ```ts
+* import { getDefaultConfig, scanRepoForVersions } from 'versionguard';
+*
+* const config = getDefaultConfig();
+* const findings = scanRepoForVersions('1.2.3', config.scan, config.ignore, process.cwd());
+* ```
+*/
+function scanRepoForVersions(expectedVersion, scanConfig, ignorePatterns, cwd = process.cwd()) {
+	const files = [...new Set(globSync("**/*", {
+		cwd,
+		absolute: true,
+		dot: true,
+		ignore: [
+			...ignorePatterns,
+			"CHANGELOG.md",
+			"*.lock",
+			"package-lock.json",
+			"yarn.lock",
+			"pnpm-lock.yaml",
+			".versionguard.yml",
+			".versionguard.yaml"
+		]
+	}))].sort();
+	const allowedFiles = new Set(scanConfig.allowlist.flatMap((entry) => resolveFiles([entry.file], cwd, [])));
+	const mismatches = [];
+	for (const filePath of files) {
+		if (BINARY_EXTENSIONS.has(path.extname(filePath).toLowerCase())) continue;
+		if (allowedFiles.has(filePath)) continue;
+		let content;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+		if (content.slice(0, 8192).includes("\0")) continue;
+		for (const patternStr of scanConfig.patterns) {
+			const regex = new RegExp(patternStr, "gm");
+			let match = regex.exec(content);
+			while (match) {
+				const found = match[1] ?? match[0] ?? "";
+				if (found && found !== expectedVersion && found !== "Unreleased") mismatches.push({
+					file: path.relative(cwd, filePath),
+					line: getLineNumber(content, match.index),
+					found
+				});
+				match = regex.exec(content);
+			}
+		}
+	}
+	return mismatches;
+}
+//#endregion
+//#region src/types.ts
+/**
+* Default SemVer configuration used when no explicit config is provided.
+*
+* @internal
+*/
+var DEFAULT_SEMVER_CONFIG = {
+	allowVPrefix: false,
+	allowBuildMetadata: true,
+	requirePrerelease: false
+};
+/**
+* Resolves the SemVer config from a VersionGuard config.
+*
+* @remarks
+* Returns the explicit `semver` block when present, otherwise falls back
+* to sensible defaults. Unlike CalVer, SemVer works out of the box without
+* explicit configuration.
+*
+* @param config - The full VersionGuard configuration object.
+* @returns The resolved SemVer configuration.
+*
+* @example
+* ```ts
+* import { getSemVerConfig } from './types';
+*
+* const sv = getSemVerConfig(config);
+* console.log(sv.allowVPrefix); // false
+* ```
+*
+* @public
+* @since 0.6.0
+*/
+function getSemVerConfig(config) {
+	return {
+		...DEFAULT_SEMVER_CONFIG,
+		...config.versioning.semver
+	};
+}
+/**
+* Extracts the CalVer config from a VersionGuard config, throwing if missing.
+*
+* @remarks
+* This is a convenience helper that validates the `calver` block exists
+* before returning it. Use this instead of accessing `config.versioning.calver`
+* directly to get a clear error when the config is misconfigured.
+*
+* @param config - The full VersionGuard configuration object.
+* @returns The validated CalVer configuration.
+*
+* @example
+* ```ts
+* import { getCalVerConfig } from './types';
+*
+* const calver = getCalVerConfig(config);
+* console.log(calver.format); // 'YYYY.MM.DD'
+* ```
+*
+* @public
+* @since 0.3.0
+*/
+function getCalVerConfig(config) {
+	if (!config.versioning.calver) throw new Error("CalVer configuration is required when versioning.type is \"calver\"");
+	return config.versioning.calver;
+}
+//#endregion
+//#region src/ckm/engine.ts
+/**
+* Topic derivation rules applied to CKM concept names.
+*
+* @remarks
+* Strips common suffixes and normalizes to lowercase slugs.
+*/
+function deriveTopicSlug(conceptName) {
+	return conceptName.replace(/Config$/, "").replace(/Result$/, "").replace(/Options$/, "").toLowerCase();
+}
+/**
+* Checks if a concept name represents a config-like topic.
+*
+* @remarks
+* Only `*Config` interfaces become topics. Result types, internal
+* types, and options are excluded from the topic index.
+*/
+function isTopicConcept(name) {
+	return name.endsWith("Config") && name !== "VersionGuardConfig";
+}
+/**
+* Matches an operation to a topic by keyword analysis.
+*
+* @remarks
+* Checks the operation name and description against the topic slug
+* and related concept names.
+*/
+function operationMatchesTopic(op, topicSlug, conceptNames) {
+	const haystack = `${op.name} ${op.what}`.toLowerCase();
+	if (haystack.includes(topicSlug)) return true;
+	return conceptNames.some((n) => haystack.includes(n.toLowerCase()));
+}
+/**
+* Creates a CKM engine from a parsed manifest.
+*
+* @remarks
+* This is the main entry point for the reusable CKM module.
+* Pass the parsed contents of `ckm.json` and get back an engine
+* that auto-derives topics and provides formatted output.
+*
+* @param manifest - Parsed CKM manifest (from forge-ts `ckm.json`).
+* @returns A configured CKM engine.
+*
+* @example
+* ```ts
+* import { createCkmEngine } from './ckm/engine';
+*
+* const engine = createCkmEngine(manifest);
+* console.log(engine.getTopicIndex('mytool'));
+* ```
+*
+* @public
+* @since 0.4.0
+*/
+function createCkmEngine(manifest) {
+	const topics = deriveTopics(manifest);
+	return {
+		topics,
+		getTopicIndex: (toolName = "tool") => formatTopicIndex(topics, toolName),
+		getTopicContent: (name) => formatTopicContent(topics, name),
+		getTopicJson: (name) => buildTopicJson(topics, manifest, name),
+		getManifest: () => manifest
+	};
+}
+/**
+* Derives topics from the CKM manifest automatically.
+*/
+function deriveTopics(manifest) {
+	const topics = [];
+	for (const concept of manifest.concepts) {
+		if (!isTopicConcept(concept.name)) continue;
+		const slug = deriveTopicSlug(concept.name);
+		const conceptNames = [concept.name];
+		const relatedConcepts = manifest.concepts.filter((c) => c.name !== concept.name && (c.name.toLowerCase().includes(slug) || slug.includes(deriveTopicSlug(c.name))));
+		conceptNames.push(...relatedConcepts.map((c) => c.name));
+		const operations = manifest.operations.filter((op) => operationMatchesTopic(op, slug, conceptNames));
+		const configSchema = manifest.configSchema.filter((c) => conceptNames.some((n) => c.key?.startsWith(n)));
+		const constraints = manifest.constraints.filter((c) => conceptNames.some((n) => c.enforcedBy?.includes(n)) || operations.some((o) => c.enforcedBy?.includes(o.name)));
+		topics.push({
+			name: slug,
+			summary: concept.what,
+			concepts: [concept, ...relatedConcepts],
+			operations,
+			configSchema,
+			constraints
+		});
+	}
+	return topics;
+}
+/**
+* Formats the topic index for terminal display.
+*/
+function formatTopicIndex(topics, toolName) {
+	const lines = [
+		`${toolName} CKM — Codebase Knowledge Manifest`,
+		"",
+		`Usage: ${toolName} ckm [topic] [--json] [--llm]`,
+		"",
+		"Topics:"
+	];
+	const maxName = Math.max(...topics.map((t) => t.name.length));
+	for (const topic of topics) lines.push(`  ${topic.name.padEnd(maxName + 2)}${topic.summary}`);
+	lines.push("");
+	lines.push("Flags:");
+	lines.push("  --json    Machine-readable CKM output (concepts, operations, config schema)");
+	lines.push("  --llm     Full API context for LLM agents (forge-ts llms.txt)");
+	return lines.join("\n");
+}
+/**
+* Formats a topic's content for human-readable terminal display.
+*/
+function formatTopicContent(topics, topicName) {
+	const topic = topics.find((t) => t.name === topicName);
+	if (!topic) return null;
+	const lines = [`# ${topic.summary}`, ""];
+	if (topic.concepts.length > 0) {
+		lines.push("## Concepts", "");
+		for (const c of topic.concepts) {
+			lines.push(`  ${c.name} — ${c.what}`);
+			if (c.properties) for (const p of c.properties) {
+				const def = findDefault(topic.configSchema, c.name, p.name);
+				lines.push(`    ${p.name}: ${p.type}${def ? ` = ${def}` : ""}`);
+				if (p.description) lines.push(`      ${p.description}`);
+			}
+			lines.push("");
+		}
+	}
+	if (topic.operations.length > 0) {
+		lines.push("## Operations", "");
+		for (const o of topic.operations) {
+			lines.push(`  ${o.name}() — ${o.what}`);
+			if (o.inputs) for (const i of o.inputs) lines.push(`    @param ${i.name}: ${i.description}`);
+			lines.push("");
+		}
+	}
+	if (topic.configSchema.length > 0) {
+		lines.push("## Config Fields", "");
+		for (const c of topic.configSchema) {
+			lines.push(`  ${c.key}: ${c.type}${c.default ? ` = ${c.default}` : ""}`);
+			if (c.description) lines.push(`    ${c.description}`);
+		}
+		lines.push("");
+	}
+	if (topic.constraints.length > 0) {
+		lines.push("## Constraints", "");
+		for (const c of topic.constraints) {
+			lines.push(`  [${c.id}] ${c.rule}`);
+			lines.push(`    Enforced by: ${c.enforcedBy}`);
+		}
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+function findDefault(schema, conceptName, propName) {
+	return schema.find((c) => c.key === `${conceptName}.${propName}`)?.default;
+}
+/**
+* Builds the JSON output for a topic or the full index.
+*/
+function buildTopicJson(topics, manifest, topicName) {
+	if (!topicName) return {
+		topics: topics.map((t) => ({
+			name: t.name,
+			summary: t.summary,
+			concepts: t.concepts.length,
+			operations: t.operations.length,
+			configFields: t.configSchema.length,
+			constraints: t.constraints.length
+		})),
+		ckm: {
+			concepts: manifest.concepts.length,
+			operations: manifest.operations.length,
+			constraints: manifest.constraints.length,
+			workflows: manifest.workflows.length,
+			configSchema: manifest.configSchema.length
+		}
+	};
+	const topic = topics.find((t) => t.name === topicName);
+	if (!topic) return {
+		error: `Unknown topic: ${topicName}`,
+		topics: topics.map((t) => t.name)
+	};
+	return {
+		topic: topic.name,
+		summary: topic.summary,
+		concepts: topic.concepts,
+		operations: topic.operations,
+		configSchema: topic.configSchema,
+		constraints: topic.constraints
+	};
+}
+//#endregion
+//#region src/config.ts
+var CONFIG_FILE_NAMES = [
+	".versionguard.yml",
+	".versionguard.yaml",
+	"versionguard.yml",
+	"versionguard.yaml"
+];
+var DEFAULT_CONFIG = {
+	versioning: {
+		type: "semver",
+		schemeRules: {
+			maxNumericSegments: 3,
+			allowedModifiers: [
+				"dev",
+				"alpha",
+				"beta",
+				"rc"
+			]
+		},
+		semver: {
+			allowVPrefix: false,
+			allowBuildMetadata: true,
+			requirePrerelease: false
+		},
+		calver: {
+			format: "YYYY.MM.PATCH",
+			preventFutureDates: true,
+			strictMutualExclusion: true
+		}
+	},
+	manifest: { source: "auto" },
+	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"
+		]
+	},
+	github: { dependabot: true },
+	scan: {
+		enabled: false,
+		patterns: [
+			"(?:version\\s*[:=]\\s*[\"'])([\\d]+\\.[\\d]+\\.[\\d]+(?:-[\\w.]+)?)[\"']",
+			"(?:FROM\\s+\\S+:)(\\d+\\.\\d+\\.\\d+(?:-[\\w.]+)?)",
+			"(?:uses:\\s+\\S+@v?)(\\d+\\.\\d+\\.\\d+(?:-[\\w.]+)?)"
+		],
+		allowlist: []
+	},
+	git: {
+		hooks: {
+			"pre-commit": true,
+			"pre-push": true,
+			"post-tag": true
+		},
+		enforceHooks: true
+	},
+	ignore: [
+		"node_modules/**",
+		"dist/**",
+		".git/**",
+		"*.lock",
+		"package-lock.json"
+	]
+};
+var MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+/**
+* Returns a deep-cloned copy of the built-in VersionGuard configuration.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* A fresh clone is returned so callers can safely modify the result without
+* mutating shared defaults.
+*
+* @returns The default VersionGuard configuration.
+* @example
+* ```ts
+* import { getDefaultConfig } from 'versionguard';
+*
+* const config = getDefaultConfig();
+* ```
+*/
+function getDefaultConfig() {
+	return structuredClone(DEFAULT_CONFIG);
+}
+/**
+* Finds the first supported VersionGuard config file in a directory.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* Search order follows `CONFIG_FILE_NAMES`, so `.versionguard.yml` takes
+* precedence over the other supported filenames.
+*
+* @param cwd - Directory to search.
+* @returns The resolved config path, or `null` when no config file exists.
+* @example
+* ```ts
+* import { findConfig } from 'versionguard';
+*
+* const configPath = findConfig(process.cwd());
+* ```
+*/
+function findConfig(cwd = process.cwd()) {
+	for (const fileName of CONFIG_FILE_NAMES) {
+		const fullPath = path.join(cwd, fileName);
+		if (fs.existsSync(fullPath)) return fullPath;
+	}
+	return null;
+}
+/**
+* Loads a VersionGuard config file from disk.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* The parsed YAML object is merged with the built-in defaults so omitted keys
+* inherit their default values.
+*
+* @param configPath - Path to the YAML config file.
+* @returns The merged VersionGuard configuration.
+* @example
+* ```ts
+* import { loadConfig } from 'versionguard';
+*
+* const config = loadConfig('.versionguard.yml');
+* ```
+*/
+function loadConfig(configPath) {
+	const content = fs.readFileSync(configPath, "utf-8");
+	const parsed = yaml.load(content);
+	if (parsed === void 0) return getDefaultConfig();
+	if (!isPlainObject(parsed)) throw new Error(`Config file must contain a YAML object: ${configPath}`);
+	return mergeDeep(getDefaultConfig(), parsed);
+}
+/**
+* Resolves the active VersionGuard configuration for a project.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* If no config file is present, this falls back to the built-in defaults.
+*
+* @param cwd - Project directory to inspect.
+* @returns The resolved VersionGuard configuration.
+* @example
+* ```ts
+* import { getConfig } from 'versionguard';
+*
+* const config = getConfig(process.cwd());
+* ```
+*/
+function getConfig(cwd = process.cwd()) {
+	const configPath = findConfig(cwd);
+	return configPath ? loadConfig(configPath) : getDefaultConfig();
+}
+/**
+* Initializes a new VersionGuard config file in a project.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This writes `.versionguard.yml` using the bundled example when available,
+* otherwise it writes a generated default configuration.
+*
+* @param cwd - Project directory where the config should be created.
+* @returns The path to the created config file.
+* @example
+* ```ts
+* import { initConfig } from 'versionguard';
+*
+* const configPath = initConfig(process.cwd());
+* ```
+*/
+function initConfig(cwd = process.cwd()) {
+	const configPath = path.join(cwd, ".versionguard.yml");
+	const existingConfigPath = findConfig(cwd);
+	if (existingConfigPath) throw new Error(`Config file already exists: ${existingConfigPath}`);
+	const examplePath = path.join(MODULE_DIR, "..", ".versionguard.yml.example");
+	const content = fs.existsSync(examplePath) ? fs.readFileSync(examplePath, "utf-8") : generateDefaultConfig();
+	fs.writeFileSync(configPath, content, "utf-8");
+	return configPath;
+}
+function generateDefaultConfig() {
+	return `# VersionGuard Configuration
+# Change "type" to switch between semver and calver — both blocks are always present.
+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
+
+github:
+  dependabot: true
+
+git:
+  hooks:
+    pre-commit: true
+    pre-push: true
+    post-tag: true
+  enforceHooks: true
+
+ignore:
+  - "node_modules/**"
+  - "dist/**"
+  - ".git/**"
+`;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeDeep(target, source) {
+	/* v8 ignore next 3 -- defensive fallback for non-object nested overrides */
+	if (!isPlainObject(target) || !isPlainObject(source)) return source ?? target;
+	const output = { ...target };
+	for (const [key, value] of Object.entries(source)) {
+		const current = output[key];
+		output[key] = isPlainObject(current) && isPlainObject(value) ? mergeDeep(current, value) : value;
+	}
+	return output;
+}
+//#endregion
+//#region src/feedback/index.ts
+/**
+* Generates actionable feedback for a version string.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This helper dispatches to the SemVer or CalVer feedback flow based on the
+* configured versioning strategy and returns both hard validation errors and
+* softer suggestions for likely fixes.
+*
+* @param version - Version string to evaluate.
+* @param config - Loaded VersionGuard configuration.
+* @param previousVersion - Optional previous version used for progression checks.
+* @returns A feedback object with validation errors and suggested fixes.
+*
+* @example
+* ```typescript
+* const feedbackResult = getVersionFeedback('1.2.3', config, '1.2.2');
+* console.log(feedbackResult.valid);
+* ```
+*/
+function getVersionFeedback(version, config, previousVersion) {
+	if (config.versioning.type === "semver") return getSemVerFeedback(version, previousVersion);
+	return getCalVerFeedback(version, getCalVerConfig(config), previousVersion);
+}
+function getSemVerFeedback(version, previousVersion) {
+	const errors = [];
+	const suggestions = [];
+	const parsed = parse$1(version);
+	if (!parsed) {
+		const validation = validate$1(version);
+		if (version.startsWith("v")) {
+			const cleanVersion = version.slice(1);
+			errors.push({
+				message: `Version should not start with 'v': ${version}`,
+				severity: "error"
+			});
+			suggestions.push({
+				message: `Remove the 'v' prefix`,
+				fix: `npx versionguard fix --version ${cleanVersion}`,
+				autoFixable: true
+			});
+		} else if (version.split(".").length === 2) {
+			errors.push({
+				message: `Version missing patch number: ${version}`,
+				severity: "error"
+			});
+			suggestions.push({
+				message: `Add patch number (e.g., ${version}.0)`,
+				fix: `npx versionguard fix --version ${version}.0`,
+				autoFixable: true
+			});
+		} else if (/^\d+\.\d+\.\d+\.\d+$/.test(version)) {
+			errors.push({
+				message: `Version has too many segments: ${version}`,
+				severity: "error"
+			});
+			suggestions.push({
+				message: `Use only 3 segments (MAJOR.MINOR.PATCH)`,
+				autoFixable: false
+			});
+		} else if (validation.errors.some((error) => error.message.includes("leading zero"))) {
+			errors.push(...validation.errors);
+			suggestions.push({
+				message: `Remove leading zeros (e.g., 1.2.3 instead of 01.02.03)`,
+				autoFixable: false
+			});
+		} else {
+			errors.push(...validation.errors.length > 0 ? validation.errors : [{
+				message: `Invalid SemVer format: ${version}`,
+				severity: "error"
+			}]);
+			suggestions.push({
+				message: `Use format: MAJOR.MINOR.PATCH (e.g., 1.0.0)`,
+				autoFixable: false
+			});
+		}
+		return {
+			valid: false,
+			errors,
+			suggestions,
+			canAutoFix: suggestions.some((s) => s.autoFixable)
+		};
+	}
+	if (previousVersion) {
+		const prevParsed = parse$1(previousVersion);
+		if (prevParsed) {
+			const comparison = compare(version, previousVersion);
+			if (comparison < 0) {
+				errors.push({
+					message: `Version ${version} is older than previous ${previousVersion}`,
+					severity: "error"
+				});
+				suggestions.push({
+					message: `Version must be greater than ${previousVersion}`,
+					fix: `npx versionguard fix --version ${increment(previousVersion, "patch")}`,
+					autoFixable: true
+				});
+			} else if (comparison === 0) {
+				errors.push({
+					message: `Version ${version} is the same as previous`,
+					severity: "error"
+				});
+				suggestions.push({
+					message: `Bump the version`,
+					fix: `npx versionguard fix --version ${increment(previousVersion, "patch")}`,
+					autoFixable: true
+				});
+			} else {
+				const majorJump = parsed.major - prevParsed.major;
+				const minorJump = parsed.minor - prevParsed.minor;
+				const patchJump = parsed.patch - prevParsed.patch;
+				if (majorJump > 1) suggestions.push({
+					message: `⚠️  Major version jumped by ${majorJump} (from ${previousVersion} to ${version})`,
+					autoFixable: false
+				});
+				if (minorJump > 10) suggestions.push({
+					message: `⚠️  Minor version jumped by ${minorJump} - did you mean to do a major bump?`,
+					autoFixable: false
+				});
+				if (patchJump > 20) suggestions.push({
+					message: `⚠️  Patch version jumped by ${patchJump} - consider a minor bump instead`,
+					autoFixable: false
+				});
+			}
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		suggestions,
+		canAutoFix: suggestions.some((s) => s.autoFixable)
+	};
+}
+function getCalVerFeedback(version, calverConfig, previousVersion) {
+	const errors = [];
+	const suggestions = [];
+	const { format, preventFutureDates } = calverConfig;
+	const parsed = parse$2(version, format);
+	if (!parsed) {
+		errors.push({
+			message: `Invalid CalVer format: ${version}`,
+			severity: "error"
+		});
+		suggestions.push({
+			message: `Expected format: ${format}`,
+			fix: `Update version to current date: "${getCurrentVersion(format)}"`,
+			autoFixable: true
+		});
+		return {
+			valid: false,
+			errors,
+			suggestions,
+			canAutoFix: true
+		};
+	}
+	const validation = validate$2(version, format, preventFutureDates);
+	errors.push(...validation.errors);
+	const now = /* @__PURE__ */ new Date();
+	if (validation.errors.some((error) => error.message.startsWith("Invalid month:"))) suggestions.push({
+		message: `Month must be between 1-12`,
+		autoFixable: false
+	});
+	if (validation.errors.some((error) => error.message.startsWith("Invalid day:"))) suggestions.push({
+		message: `Day must be valid for the selected month`,
+		autoFixable: false
+	});
+	if (preventFutureDates && parsed.year > now.getFullYear()) suggestions.push({
+		message: `Use current year (${now.getFullYear()}) or a past year`,
+		fix: `npx versionguard fix --version ${formatCalVerVersion({
+			...parsed,
+			year: now.getFullYear()
+		})}`,
+		autoFixable: true
+	});
+	if (preventFutureDates && parsed.year === now.getFullYear() && parsed.month > now.getMonth() + 1) suggestions.push({
+		message: `Current month is ${now.getMonth() + 1}`,
+		fix: `npx versionguard fix --version ${formatCalVerVersion({
+			...parsed,
+			month: now.getMonth() + 1
+		})}`,
+		autoFixable: true
+	});
+	if (preventFutureDates && parsed.year === now.getFullYear() && parsed.month === now.getMonth() + 1 && parsed.day !== void 0 && parsed.day > now.getDate()) suggestions.push({
+		message: `Current day is ${now.getDate()}`,
+		fix: `npx versionguard fix --version ${formatCalVerVersion({
+			...parsed,
+			day: now.getDate()
+		})}`,
+		autoFixable: true
+	});
+	if (previousVersion) {
+		if (parse$2(previousVersion, format)) {
+			if (compare$1(version, previousVersion, format) <= 0) {
+				errors.push({
+					message: `Version ${version} is not newer than previous ${previousVersion}`,
+					severity: "error"
+				});
+				suggestions.push({
+					message: `CalVer must increase over time`,
+					fix: `npx versionguard fix --version ${increment$1(previousVersion, format)}`,
+					autoFixable: true
+				});
+			}
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		suggestions,
+		canAutoFix: suggestions.some((s) => s.autoFixable)
+	};
+}
+function formatCalVerVersion(version) {
+	return format$1({
+		...version,
+		raw: version.raw || ""
+	});
+}
+/**
+* Generates suggestions for version sync mismatches in a file.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* The returned suggestions include a general sync command and may include
+* file-type-specific hints for markdown or source files.
+*
+* @param file - File containing the mismatched version string.
+* @param foundVersion - Version currently found in the file.
+* @param expectedVersion - Version that should appear in the file.
+* @returns Suggestions for resolving the mismatch.
+*
+* @example
+* ```typescript
+* const suggestions = getSyncFeedback('README.md', '1.0.0', '1.0.1');
+* console.log(suggestions[0]?.message);
+* ```
+*/
+function getSyncFeedback(file, foundVersion, expectedVersion) {
+	const suggestions = [{
+		message: `${file} has version "${foundVersion}" but should be "${expectedVersion}"`,
+		fix: `npx versionguard sync`,
+		autoFixable: true
+	}];
+	if (file.endsWith(".md")) suggestions.push({
+		message: `For markdown files, check headers like "## [${expectedVersion}]"`,
+		autoFixable: false
+	});
+	if (file.endsWith(".ts") || file.endsWith(".js")) suggestions.push({
+		message: `For code files, check constants like "export const VERSION = '${expectedVersion}'"`,
+		autoFixable: false
+	});
+	return suggestions;
+}
+/**
+* Generates suggestions for changelog-related validation issues.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This helper suggests either creating a missing entry or reconciling the latest
+* changelog version with the package version.
+*
+* @param hasEntry - Whether the changelog already contains an entry for the version.
+* @param version - Package version that should appear in the changelog.
+* @param latestChangelogVersion - Most recent version currently found in the changelog.
+* @returns Suggestions for bringing changelog state back into sync.
+*
+* @example
+* ```typescript
+* const suggestions = getChangelogFeedback(false, '1.2.3', '1.2.2');
+* console.log(suggestions.length > 0);
+* ```
+*/
+function getChangelogFeedback(hasEntry, version, latestChangelogVersion) {
+	const suggestions = [];
+	if (!hasEntry) {
+		suggestions.push({
+			message: `CHANGELOG.md is missing entry for version ${version}`,
+			fix: `npx versionguard fix`,
+			autoFixable: true
+		});
+		suggestions.push({
+			message: `Or manually add: "## [${version}] - YYYY-MM-DD" under [Unreleased]`,
+			autoFixable: false
+		});
+	}
+	if (latestChangelogVersion && latestChangelogVersion !== version) suggestions.push({
+		message: `CHANGELOG.md latest entry is ${latestChangelogVersion}, but manifest version is ${version}`,
+		fix: `Make sure versions are in sync`,
+		autoFixable: false
+	});
+	return suggestions;
+}
+/**
+* Generates suggestions for git tag mismatches.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This helper focuses on discrepancies between git tag versions, package.json,
+* and repository files that still need to be synchronized.
+*
+* @param tagVersion - Version represented by the git tag.
+* @param packageVersion - Version currently stored in `package.json`.
+* @param hasUnsyncedFiles - Whether repository files are still out of sync.
+* @returns Suggestions for correcting tag-related issues.
+*
+* @example
+* ```typescript
+* const suggestions = getTagFeedback('v1.2.2', '1.2.3', true);
+* console.log(suggestions.map((item) => item.message));
+* ```
+*/
+function getTagFeedback(tagVersion, packageVersion, hasUnsyncedFiles) {
+	const suggestions = [];
+	if (tagVersion !== packageVersion) suggestions.push({
+		message: `Git tag "${tagVersion}" doesn't match manifest version "${packageVersion}"`,
+		fix: `Delete tag and recreate: git tag -d ${tagVersion} && git tag ${packageVersion}`,
+		autoFixable: false
+	});
+	if (hasUnsyncedFiles) suggestions.push({
+		message: `Files are out of sync with version ${packageVersion}`,
+		fix: `npx versionguard sync`,
+		autoFixable: true
+	});
+	return suggestions;
+}
+//#endregion
+//#region src/fix/index.ts
+/**
+* Updates the `package.json` version field when needed.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This helper writes the target version only when `package.json` exists and the
+* current version differs from the requested value.
+*
+* @param targetVersion - Version that should be written to `package.json`.
+* @param cwd - Repository directory containing `package.json`.
+* @param manifest - Optional manifest configuration for language-agnostic support.
+* @returns The result of the package version fix attempt.
+*
+* @example
+* ```typescript
+* // Fix using legacy package.json fallback
+* const result = fixPackageVersion('1.2.3', process.cwd());
+* console.log(result.fixed);
+*
+* // Fix using a configured manifest source
+* const result2 = fixPackageVersion('1.2.3', process.cwd(), { source: 'Cargo.toml' });
+* ```
+*/
+function fixPackageVersion(targetVersion, cwd = process.cwd(), manifest) {
+	if (!manifest) {
+		const packagePath = path.join(cwd, "package.json");
+		if (!fs.existsSync(packagePath)) return {
+			fixed: false,
+			message: "package.json not found"
+		};
+		const pkg = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+		const oldVersion = typeof pkg.version === "string" ? pkg.version : void 0;
+		if (oldVersion === targetVersion) return {
+			fixed: false,
+			message: `Already at version ${targetVersion}`
+		};
+		setPackageVersion(targetVersion, cwd);
+		return {
+			fixed: true,
+			message: `Updated package.json from ${oldVersion} to ${targetVersion}`,
+			file: packagePath
+		};
+	}
+	const provider = getVersionSource(manifest, cwd);
+	let oldVersion;
+	try {
+		oldVersion = provider.getVersion(cwd);
+	} catch {
+		return {
+			fixed: false,
+			message: "Version source not found"
+		};
+	}
+	if (oldVersion === targetVersion) return {
+		fixed: false,
+		message: `Already at version ${targetVersion}`
+	};
+	provider.setVersion(targetVersion, cwd);
+	return {
+		fixed: true,
+		message: `Updated version from ${oldVersion} to ${targetVersion}`,
+		file: provider.manifestFile ? path.join(cwd, provider.manifestFile) : void 0
+	};
+}
+/**
+* Synchronizes configured files to the package version.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This helper uses the configured sync targets to update version strings across
+* the repository and reports only the files that changed.
+*
+* @param config - Loaded VersionGuard configuration.
+* @param cwd - Repository directory to synchronize.
+* @returns A list of per-file sync results.
+*
+* @example
+* ```typescript
+* const results = fixSyncIssues(config, process.cwd());
+* console.log(results.length);
+* ```
+*/
+function fixSyncIssues(config, cwd = process.cwd()) {
+	const results = syncVersion(getPackageVersion(cwd, config.manifest), config.sync, cwd).filter((result) => result.updated).map((result) => ({
+		fixed: true,
+		message: `Updated ${path.relative(cwd, result.file)} (${result.changes.length} changes)`,
+		file: result.file
+	}));
+	if (results.length === 0) results.push({
+		fixed: false,
+		message: "All files already in sync"
+	});
+	return results;
+}
+/**
+* Ensures the changelog contains an entry for a version.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* When the changelog file does not exist, this helper creates a starter changelog.
+* Otherwise it appends a new version entry only when one is missing.
+*
+* @param version - Version that should appear in the changelog.
+* @param config - Loaded VersionGuard configuration.
+* @param cwd - Repository directory containing the changelog file.
+* @returns The result of the changelog fix attempt.
+*
+* @example
+* ```typescript
+* const result = fixChangelog('1.2.3', config, process.cwd());
+* console.log(result.message);
+* ```
+*/
+function fixChangelog(version, config, cwd = process.cwd()) {
+	const changelogPath = path.join(cwd, config.changelog.file);
+	if (!fs.existsSync(changelogPath)) {
+		createInitialChangelog(changelogPath, version);
+		return {
+			fixed: true,
+			message: `Created ${config.changelog.file} with entry for ${version}`,
+			file: changelogPath
+		};
+	}
+	if (fs.readFileSync(changelogPath, "utf-8").includes(`## [${version}]`)) return {
+		fixed: false,
+		message: `Changelog already has entry for ${version}`
+	};
+	addVersionEntry(changelogPath, version);
+	return {
+		fixed: true,
+		message: `Added entry for ${version} to ${config.changelog.file}`,
+		file: changelogPath
+	};
+}
+/**
+* Create initial changelog
+*/
+function createInitialChangelog(changelogPath, version) {
+	const content = `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [${version}] - ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}
+
+### Added
+
+- Initial release
+
+[Unreleased]: https://github.com/yourorg/project/compare/v${version}...HEAD
+[${version}]: https://github.com/yourorg/project/releases/tag/v${version}
+`;
+	fs.writeFileSync(changelogPath, content, "utf-8");
+}
+/**
+* Runs all configured auto-fix operations.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This helper optionally updates the package version first, then synchronizes
+* configured files, and finally updates the changelog when changelog support is
+* enabled.
+*
+* @param config - Loaded VersionGuard configuration.
+* @param targetVersion - Optional version to apply before running other fixes.
+* @param cwd - Repository directory where fixes should run.
+* @returns Ordered results describing every fix step that ran.
+*
+* @example
+* ```typescript
+* const results = fixAll(config, '1.2.3', process.cwd());
+* console.log(results.some((result) => result.fixed));
+* ```
+*/
+function fixAll(config, targetVersion, cwd = process.cwd()) {
+	const results = [];
+	const version = targetVersion || getPackageVersion(cwd, config.manifest);
+	if (targetVersion && targetVersion !== getPackageVersion(cwd, config.manifest)) results.push(fixPackageVersion(targetVersion, cwd, config.manifest));
+	const syncResults = fixSyncIssues(config, cwd);
+	results.push(...syncResults);
+	if (config.changelog.enabled) {
+		const changelogPath = path.join(cwd, config.changelog.file);
+		if (isChangesetMangled(changelogPath)) {
+			if (fixChangesetMangling(changelogPath)) results.push({
+				fixed: true,
+				message: `Restructured ${config.changelog.file} from Changesets format to Keep a Changelog`,
+				file: changelogPath
+			});
+		}
+		const changelogResult = fixChangelog(version, config, cwd);
+		if (changelogResult.fixed) results.push(changelogResult);
+	}
+	return results;
+}
+/**
+* Suggests candidate next versions for a release.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* The suggestions depend on the configured versioning mode. SemVer returns one or
+* more bump options, while CalVer suggests the current date-based version and an
+* incremented same-day release.
+*
+* @param currentVersion - Current package version.
+* @param config - Loaded VersionGuard configuration.
+* @param changeType - Preferred bump type, or `auto` to include common options.
+* @returns Candidate versions paired with the reason for each suggestion.
+*
+* @example
+* ```typescript
+* const suggestions = suggestNextVersion('1.2.3', config, 'minor');
+* console.log(suggestions[0]?.version);
+* ```
+*/
+function suggestNextVersion(currentVersion, config, changeType) {
+	const suggestions = [];
+	if (config.versioning.type === "semver") {
+		if (!changeType || changeType === "auto" || changeType === "patch") suggestions.push({
+			version: increment(currentVersion, "patch"),
+			reason: "Patch - bug fixes, small changes"
+		});
+		if (!changeType || changeType === "auto" || changeType === "minor") suggestions.push({
+			version: increment(currentVersion, "minor"),
+			reason: "Minor - new features, backwards compatible"
+		});
+		if (!changeType || changeType === "auto" || changeType === "major") suggestions.push({
+			version: increment(currentVersion, "major"),
+			reason: "Major - breaking changes"
+		});
+	} else {
+		const format = getCalVerConfig(config).format;
+		const currentCal = getCurrentVersion(format);
+		suggestions.push({
+			version: currentCal,
+			reason: "Current date - new release today"
+		});
+		suggestions.push({
+			version: increment$1(currentVersion, format),
+			reason: "Increment patch - additional release today"
+		});
+	}
+	return suggestions;
+}
+//#endregion
+//#region src/guard.ts
+var HOOK_NAMES = [
+	"pre-commit",
+	"pre-push",
+	"post-tag"
+];
+/**
+* Checks whether git hooks have been redirected away from the repository.
+*
+* @remarks
+* When `core.hooksPath` is set to a non-default location, git hooks installed
+* in `.git/hooks/` are silently ignored. This is a common bypass vector.
+*
+* @param cwd - Repository directory to inspect.
+* @returns A guard warning when a hooksPath override is detected.
+*
+* @example
+* ```ts
+* import { checkHooksPathOverride } from './guard';
+*
+* const warning = checkHooksPathOverride(process.cwd());
+* if (warning) console.warn(warning.message);
+* ```
+*
+* @public
+* @since 0.2.0
+*/
+function checkHooksPathOverride(cwd) {
+	try {
+		const hooksPath = execSync("git config core.hooksPath", {
+			cwd,
+			encoding: "utf-8"
+		}).trim();
+		if (hooksPath) {
+			const resolved = path.resolve(cwd, hooksPath);
+			const huskyDir = path.resolve(cwd, ".husky");
+			if (resolved === huskyDir || resolved.startsWith(`${huskyDir}${path.sep}`)) return {
+				code: "HOOKS_PATH_HUSKY",
+				severity: "warning",
+				message: `Husky detected — core.hooksPath is set to "${hooksPath}". Hooks in .git/hooks/ are bypassed. Add versionguard validate to your .husky/pre-commit manually or use a tool like forge-ts that manages .husky/ hooks cooperatively.`
+			};
+			return {
+				code: "HOOKS_PATH_OVERRIDE",
+				severity: "error",
+				message: `git core.hooksPath is set to "${hooksPath}" — hooks in .git/hooks/ are bypassed`,
+				fix: "git config --unset core.hooksPath"
+			};
+		}
+	} catch {}
+	return null;
+}
+/**
+* Checks whether the HUSKY environment variable is disabling hooks.
+*
+* @remarks
+* Setting `HUSKY=0` is a documented way to disable Husky hooks. Since
+* VersionGuard hooks may run alongside or through Husky, this bypass
+* can silently disable enforcement.
+*
+* @returns A guard warning when the HUSKY bypass is detected.
+*
+* @example
+* ```ts
+* import { checkHuskyBypass } from './guard';
+*
+* const warning = checkHuskyBypass();
+* if (warning) console.warn(warning.message);
+* ```
+*
+* @public
+* @since 0.2.0
+*/
+function checkHuskyBypass() {
+	if (process.env.HUSKY === "0") return {
+		code: "HUSKY_BYPASS",
+		severity: "error",
+		message: "HUSKY=0 is set — git hooks are disabled via environment variable",
+		fix: "unset HUSKY"
+	};
+	return null;
+}
+/**
+* Verifies that installed hook scripts match the expected content.
+*
+* @remarks
+* This compares each hook file against what `generateHookScript` would produce.
+* Tampered hooks that still contain "versionguard" pass `areHooksInstalled` but
+* may have had critical lines removed or modified.
+*
+* @param config - VersionGuard configuration that defines which hooks should exist.
+* @param cwd - Repository directory to inspect.
+* @returns Guard warnings for each hook that has been tampered with.
+*
+* @example
+* ```ts
+* import { checkHookIntegrity } from './guard';
+*
+* const warnings = checkHookIntegrity(config, process.cwd());
+* for (const w of warnings) console.warn(w.code, w.message);
+* ```
+*
+* @public
+* @since 0.2.0
+*/
+function checkHookIntegrity(config, cwd) {
+	const warnings = [];
+	const gitDir = findGitDir(cwd);
+	if (!gitDir) return warnings;
+	const hooksDir = path.join(gitDir, "hooks");
+	for (const hookName of HOOK_NAMES) {
+		if (!config.git.hooks[hookName]) continue;
+		const hookPath = path.join(hooksDir, hookName);
+		if (!fs.existsSync(hookPath)) {
+			warnings.push({
+				code: "HOOK_MISSING",
+				severity: "error",
+				message: `Required hook "${hookName}" is not installed`,
+				fix: "npx versionguard hooks install"
+			});
+			continue;
+		}
+		const actual = fs.readFileSync(hookPath, "utf-8");
+		if (actual !== generateHookScript(hookName)) if (!actual.includes("versionguard")) warnings.push({
+			code: "HOOK_REPLACED",
+			severity: "error",
+			message: `Hook "${hookName}" has been replaced — versionguard invocation is missing`,
+			fix: "npx versionguard hooks install"
+		});
+		else warnings.push({
+			code: "HOOK_TAMPERED",
+			severity: "warning",
+			message: `Hook "${hookName}" has been modified from the expected template`,
+			fix: "npx versionguard hooks install"
+		});
+	}
+	return warnings;
+}
+/**
+* Checks whether hooks are configured as required but not enforced.
+*
+* @remarks
+* When hooks are enabled in the config but `enforceHooks` is false, validation
+* will not fail for missing hooks. In strict mode this is a policy gap.
+*
+* @param config - VersionGuard configuration to inspect.
+* @returns A guard warning when hooks are enabled but not enforced.
+*
+* @example
+* ```ts
+* import { checkEnforceHooksPolicy } from './guard';
+*
+* const warning = checkEnforceHooksPolicy(config);
+* if (warning) console.warn(warning.message);
+* ```
+*
+* @public
+* @since 0.2.0
+*/
+function checkEnforceHooksPolicy(config) {
+	if (HOOK_NAMES.some((name) => config.git.hooks[name]) && !config.git.enforceHooks) return {
+		code: "HOOKS_NOT_ENFORCED",
+		severity: "warning",
+		message: "Hooks are enabled but enforceHooks is false — missing hooks will not fail validation",
+		fix: "Set git.enforceHooks: true in .versionguard.yml"
+	};
+	return null;
+}
+/**
+* Runs all guard checks and returns a consolidated report.
+*
+* @remarks
+* This is the primary entry point for strict mode. It runs every detection
+* check and returns a report indicating whether the repository is safe from
+* known bypass patterns.
+*
+* @param config - VersionGuard configuration.
+* @param cwd - Repository directory to inspect.
+* @returns A guard report with all findings.
+*
+* @example
+* ```ts
+* import { runGuardChecks } from './guard';
+*
+* const report = runGuardChecks(config, process.cwd());
+* if (!report.safe) console.error('Guard check failed:', report.warnings);
+* ```
+*
+* @public
+* @since 0.2.0
+*/
+function runGuardChecks(config, cwd) {
+	const warnings = [];
+	const hooksPathWarning = checkHooksPathOverride(cwd);
+	if (hooksPathWarning) warnings.push(hooksPathWarning);
+	const huskyWarning = checkHuskyBypass();
+	if (huskyWarning) warnings.push(huskyWarning);
+	const integrityWarnings = checkHookIntegrity(config, cwd);
+	warnings.push(...integrityWarnings);
+	const enforceWarning = checkEnforceHooksPolicy(config);
+	if (enforceWarning) warnings.push(enforceWarning);
+	return {
+		safe: !warnings.some((w) => w.severity === "error"),
+		warnings
+	};
+}
+//#endregion
+//#region src/project-root.ts
+/**
+* Project root detection and boundary validation.
+*
+* @packageDocumentation
+*/
+/** Files that indicate a project root directory. */
+var PROJECT_MARKERS = [
+	".versionguard.yml",
+	".versionguard.yaml",
+	"versionguard.yml",
+	"versionguard.yaml",
+	".git",
+	"package.json",
+	"Cargo.toml",
+	"pyproject.toml",
+	"pubspec.yaml",
+	"composer.json",
+	"pom.xml",
+	"go.mod",
+	"mix.exs",
+	"Gemfile",
+	".csproj"
+];
+/**
+* Walks up from `startDir` to find the nearest project root.
+*
+* @remarks
+* Checks for VersionGuard config files first, then `.git`, then manifest files.
+* Stops at the filesystem root if nothing is found.
+*
+* @param startDir - Directory to start searching from.
+* @returns Detection result with the project root path and what was found.
+*
+* @example
+* ```ts
+* import { findProjectRoot } from 'versionguard';
+*
+* const result = findProjectRoot(process.cwd());
+* if (!result.found) {
+*   console.log('Not in a project directory');
+* }
+* ```
+*
+* @public
+* @since 0.4.0
+*/
+function findProjectRoot(startDir) {
+	let current = path.resolve(startDir);
+	while (true) {
+		for (const marker of PROJECT_MARKERS) if (marker.startsWith(".") && marker !== ".git" && !marker.startsWith(".version")) try {
+			if (fs.readdirSync(current).some((f) => f.endsWith(marker))) return buildResult(current, marker);
+		} catch {}
+		else if (fs.existsSync(path.join(current, marker))) return buildResult(current, marker);
+		const parent = path.dirname(current);
+		if (parent === current) return {
+			found: false,
+			root: path.resolve(startDir),
+			hasConfig: false,
+			hasGit: false,
+			hasManifest: false
+		};
+		current = parent;
+	}
+}
+function buildResult(root, marker) {
+	return {
+		found: true,
+		root,
+		marker,
+		hasConfig: [
+			".versionguard.yml",
+			".versionguard.yaml",
+			"versionguard.yml",
+			"versionguard.yaml"
+		].some((c) => fs.existsSync(path.join(root, c))),
+		hasGit: fs.existsSync(path.join(root, ".git")),
+		hasManifest: [
+			"package.json",
+			"Cargo.toml",
+			"pyproject.toml",
+			"pubspec.yaml",
+			"composer.json",
+			"pom.xml",
+			"VERSION"
+		].some((m) => fs.existsSync(path.join(root, m)))
+	};
+}
+/**
+* Formats a helpful error message when a command can't find a project.
+*
+* @remarks
+* The message includes actionable hints such as running `versionguard init` or
+* changing to a project root directory. Useful for CLI commands that require a
+* VersionGuard-enabled project.
+*
+* @param cwd - The directory that was checked.
+* @param command - The command that was attempted.
+* @returns A formatted, helpful error message.
+*
+* @example
+* ```ts
+* import { formatNotProjectError } from 'versionguard';
+*
+* const msg = formatNotProjectError('/tmp/empty', 'validate');
+* console.error(msg);
+* ```
+*
+* @public
+* @since 0.4.0
+*/
+function formatNotProjectError(cwd, command) {
+	return [
+		`Not a VersionGuard project: ${path.basename(cwd) || cwd}`,
+		"",
+		"No .versionguard.yml, .git directory, or manifest file found.",
+		"",
+		"To get started:",
+		"  versionguard init          Set up a new project interactively",
+		"  versionguard init --yes    Set up with defaults",
+		"",
+		"Or run from a project root directory:",
+		`  cd /path/to/project && versionguard ${command}`
+	].join("\n");
+}
+//#endregion
+//#region src/tag/index.ts
+function runGit(cwd, args, encoding) {
+	return childProcess.execFileSync("git", args, {
+		cwd,
+		encoding,
+		stdio: [
+			"pipe",
+			"pipe",
+			"ignore"
+		]
+	});
+}
+function runGitText(cwd, args) {
+	return runGit(cwd, args, "utf-8");
+}
+/**
+* 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);
+* }
+* ```
+*/
+function getLatestTag(cwd = process.cwd()) {
+	try {
+		const tagName = runGitText(cwd, [
+			"describe",
+			"--tags",
+			"--abbrev=0"
+		]).trim();
+		const version = tagName.replace(/^v/, "");
+		const dateResult = runGitText(cwd, [
+			"log",
+			"-1",
+			"--format=%ai",
+			tagName
+		]);
+		const message = runGitText(cwd, [
+			"tag",
+			"-l",
+			tagName,
+			"--format=%(contents)"
+		]).trim();
+		return {
+			name: tagName,
+			version,
+			message: message.length > 0 ? message : void 0,
+			date: new Date(dateResult.trim())
+		};
+	} catch {
+		return 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));
+* ```
+*/
+function getAllTags(cwd = process.cwd()) {
+	try {
+		return runGitText(cwd, ["tag", "--list"]).trim().split("\n").filter(Boolean).map((name) => ({
+			name,
+			version: name.replace(/^v/, ""),
+			date: /* @__PURE__ */ new Date()
+		}));
+	} catch {
+		return [];
+	}
+}
+/**
+* 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);
+* }
+* ```
+*/
+function createTag(version, message, autoFix = true, config, cwd = process.cwd()) {
+	const actions = [];
+	try {
+		if (!config) return {
+			success: false,
+			message: "VersionGuard config is required to create tags safely",
+			actions
+		};
+		const packageVersion = getPackageVersion(cwd, config.manifest);
+		const preflightError = getTagPreflightError(config, cwd, version, autoFix);
+		if (preflightError) return {
+			success: false,
+			message: preflightError,
+			actions
+		};
+		if (version !== packageVersion && !autoFix) return {
+			success: false,
+			message: `Version mismatch: manifest version is ${packageVersion}, tag is ${version}`,
+			actions: []
+		};
+		if (autoFix) {
+			const fixResults = version !== packageVersion ? fixAll(config, version, cwd) : fixAll(config, void 0, cwd);
+			for (const result of fixResults) if (result.fixed) actions.push(result.message);
+			if (fixResults.some((result) => result.fixed)) {
+				runGit(cwd, ["add", "-A"]);
+				runGit(cwd, [
+					"commit",
+					"--no-verify",
+					"-m",
+					`chore(release): ${version}`
+				]);
+				actions.push("Committed version changes");
+			}
+		}
+		const tagName = `v${version}`;
+		const tagMessage = message || `Release ${version}`;
+		if (getAllTags(cwd).some((tag) => tag.name === tagName)) return {
+			success: false,
+			message: `Tag ${tagName} already exists`,
+			actions
+		};
+		runGit(cwd, [
+			"tag",
+			"-a",
+			tagName,
+			"-m",
+			tagMessage
+		]);
+		actions.push(`Created tag ${tagName}`);
+		return {
+			success: true,
+			message: `Successfully created tag ${tagName}`,
+			actions
+		};
+	} catch (err) {
+		return {
+			success: false,
+			message: `Failed to create tag: ${err.message}`,
+			actions
+		};
+	}
+}
+/**
+* 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);
+* ```
+*/
+function handlePostTag(config, cwd = process.cwd()) {
+	const actions = [];
+	try {
+		const preflightError = getTagPreflightError(config, cwd);
+		if (preflightError) return {
+			success: false,
+			message: preflightError,
+			actions
+		};
+		const tag = getLatestTag(cwd);
+		if (!tag) return {
+			success: false,
+			message: "No tag found",
+			actions
+		};
+		const packageVersion = getPackageVersion(cwd, config.manifest);
+		if (tag.version !== packageVersion) return {
+			success: false,
+			message: `Tag version ${tag.version} doesn't match manifest version ${packageVersion}`,
+			actions: [
+				"To fix: delete tag and recreate with correct version",
+				`  git tag -d ${tag.name}`,
+				`  Update manifest to ${tag.version}`,
+				`  git tag ${tag.name}`
+			]
+		};
+		const syncResults = fixAll(config, packageVersion, cwd);
+		for (const result of syncResults)
+ /* v8 ignore next 3 -- preflight blocks remaining post-tag fixes */
+		if (result.fixed) actions.push(result.message);
+		return {
+			success: true,
+			message: `Post-tag workflow completed for ${tag.name}`,
+			actions
+		};
+	} catch (err) {
+		return {
+			success: false,
+			message: `Post-tag workflow failed: ${err.message}`,
+			actions
+		};
+	}
+}
+function getTagPreflightError(config, cwd, expectedVersion, allowAutoFix = false) {
+	if (config.git.enforceHooks && !areHooksInstalled(cwd)) return "Git hooks must be installed before creating or validating release tags";
+	if (hasDirtyWorktree(cwd)) return "Working tree must be clean before creating or validating release tags";
+	const version = expectedVersion ?? getPackageVersion(cwd, config.manifest);
+	const versionResult = config.versioning.type === "semver" ? validate$1(version, getSemVerConfig(config), config.versioning.schemeRules) : validate$2(version, config.versioning.calver?.format ?? "YYYY.MM.PATCH", config.versioning.calver?.preventFutureDates ?? true, config.versioning.schemeRules);
+	if (!versionResult.valid) return versionResult.errors[0]?.message ?? `Invalid version: ${version}`;
+	if (allowAutoFix) return null;
+	const mismatches = checkHardcodedVersions(version, config.sync, config.ignore, cwd);
+	if (mismatches.length > 0) {
+		const mismatch = mismatches[0];
+		return `Version mismatch in ${mismatch.file}:${mismatch.line} - found "${mismatch.found}" but expected "${version}"`;
+	}
+	const changelogResult = validateChangelog(path.join(cwd, config.changelog.file), version, config.changelog.strict, config.changelog.requireEntry, {
+		enforceStructure: config.changelog.enforceStructure,
+		sections: config.changelog.sections
+	});
+	if (!changelogResult.valid) return changelogResult.errors[0] ?? "Changelog validation failed";
+	return null;
+}
+function hasDirtyWorktree(cwd) {
+	try {
+		return runGitText(cwd, ["status", "--porcelain"]).trim().length > 0;
+	} catch {
+		return true;
+	}
+}
+/**
+* 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);
+* ```
+*/
+function validateTagForPush(tagName, cwd = process.cwd()) {
+	try {
+		runGit(cwd, ["rev-parse", tagName]);
+		try {
+			runGit(cwd, [
+				"ls-remote",
+				"--tags",
+				"origin",
+				tagName
+			]);
+			const localHash = runGitText(cwd, ["rev-parse", tagName]).trim();
+			const remoteOutput = runGitText(cwd, [
+				"ls-remote",
+				"--tags",
+				"origin",
+				tagName
+			]).trim();
+			if (remoteOutput && !remoteOutput.includes(localHash)) return {
+				valid: false,
+				message: `Tag ${tagName} exists on remote with different commit`,
+				fix: `Delete remote tag first: git push origin :refs/tags/${tagName}`
+			};
+		} catch {
+			return {
+				valid: true,
+				message: `Tag ${tagName} is valid for push`
+			};
+		}
+		return {
+			valid: true,
+			message: `Tag ${tagName} is valid for push`
+		};
+	} catch {
+		return {
+			valid: false,
+			message: `Tag ${tagName} not found locally`,
+			fix: `Create tag: git tag ${tagName}`
+		};
+	}
+}
+/**
+* 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);
+* ```
+*/
+function suggestTagMessage(version, cwd = process.cwd()) {
+	try {
+		const changelogPath = path.join(cwd, "CHANGELOG.md");
+		if (fs.existsSync(changelogPath)) {
+			const content = fs.readFileSync(changelogPath, "utf-8");
+			const versionRegex = new RegExp(`## \\[${version}\\].*?\\n(.*?)(?=\\n## \\[|\\n\\n## |$)`, "s");
+			const match = content.match(versionRegex);
+			if (match) {
+				const bulletMatch = match[1].match(/- (.+)/);
+				if (bulletMatch) return `Release ${version}: ${bulletMatch[1].trim()}`;
+			}
+		}
+	} catch {
+		return `Release ${version}`;
+	}
+	return `Release ${version}`;
+}
+//#endregion
+//#region src/index.ts
+/**
+* Public API for VersionGuard.
+*
+* @packageDocumentation
+* @public
+*/
+/**
+* Validates a version string against the active versioning strategy.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This helper dispatches to SemVer or CalVer validation based on
+* `config.versioning.type`.
+*
+* @param version - Version string to validate.
+* @param config - VersionGuard configuration that selects the validation rules.
+* @returns The validation result for the provided version.
+* @example
+* ```ts
+* import { getDefaultConfig, validateVersion } from 'versionguard';
+*
+* const result = validateVersion('1.2.3', getDefaultConfig());
+* ```
+*/
+function validateVersion(version, config) {
+	if (config.versioning.type === "semver") return validate$1(version, getSemVerConfig(config), config.versioning.schemeRules);
+	const calverConfig = getCalVerConfig(config);
+	return validate$2(version, calverConfig.format, calverConfig.preventFutureDates, config.versioning.schemeRules);
+}
+/**
+* Validates the current project state against the supplied configuration.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This reads the package version from `package.json`, validates the version
+* format, checks synchronized files, and optionally validates the changelog.
+*
+* @param config - VersionGuard configuration to apply.
+* @param cwd - Project directory to inspect.
+* @returns A full validation report for the project rooted at `cwd`.
+* @example
+* ```ts
+* import { getDefaultConfig, validate } from 'versionguard';
+*
+* const result = validate(getDefaultConfig(), process.cwd());
+* ```
+*/
+function validate(config, cwd = process.cwd()) {
+	const errors = [];
+	let version;
+	try {
+		version = getPackageVersion(cwd, config.manifest);
+	} catch (err) {
+		return {
+			valid: false,
+			version: "",
+			versionValid: false,
+			syncValid: false,
+			changelogValid: false,
+			errors: [err.message]
+		};
+	}
+	const versionResult = validateVersion(version, config);
+	if (!versionResult.valid) errors.push(...versionResult.errors.map((error) => error.message));
+	const hardcoded = checkHardcodedVersions(version, config.sync, config.ignore, cwd);
+	if (hardcoded.length > 0) for (const mismatch of hardcoded) errors.push(`Version mismatch in ${mismatch.file}:${mismatch.line} - found "${mismatch.found}" but expected "${version}"`);
+	if (config.scan?.enabled) {
+		const scanFindings = scanRepoForVersions(version, config.scan, config.ignore, cwd);
+		for (const finding of scanFindings) errors.push(`Stale version in ${finding.file}:${finding.line} - found "${finding.found}" but expected "${version}"`);
+	}
+	let changelogValid = true;
+	if (config.changelog.enabled) {
+		const changelogResult = validateChangelog(path.join(cwd, config.changelog.file), version, config.changelog.strict, config.changelog.requireEntry, {
+			enforceStructure: config.changelog.enforceStructure,
+			sections: config.changelog.sections
+		});
+		if (!changelogResult.valid) {
+			changelogValid = false;
+			errors.push(...changelogResult.errors);
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		version,
+		versionValid: versionResult.valid,
+		syncValid: hardcoded.length === 0,
+		changelogValid,
+		errors
+	};
+}
+/**
+* Runs an extended readiness check for a project.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* In addition to `validate`, this inspects Git state so callers can determine
+* whether hooks are installed and the worktree is clean.
+*
+* @param config - VersionGuard configuration to apply.
+* @param cwd - Project directory to inspect.
+* @returns A readiness report that includes validation and Git diagnostics.
+* @example
+* ```ts
+* import { doctor, getDefaultConfig } from 'versionguard';
+*
+* const report = doctor(getDefaultConfig(), process.cwd());
+* ```
+*/
+function doctor(config, cwd = process.cwd()) {
+	const validation = validate(config, cwd);
+	const gitRepository = findGitDir(cwd) !== null;
+	const hooksInstalled = gitRepository ? areHooksInstalled(cwd) : false;
+	const worktreeClean = gitRepository ? isWorktreeClean(cwd) : true;
+	const errors = [...validation.errors];
+	if (gitRepository && config.git.enforceHooks && !hooksInstalled) errors.push("Git hooks are not installed");
+	if (gitRepository && !worktreeClean) errors.push("Working tree is not clean");
+	if (gitRepository && config.github?.dependabot && !dependabotConfigExists(cwd)) errors.push(".github/dependabot.yml is missing — run `vg init` to generate it");
+	return {
+		ready: errors.length === 0,
+		version: validation.version,
+		versionValid: validation.versionValid,
+		syncValid: validation.syncValid,
+		changelogValid: validation.changelogValid,
+		gitRepository,
+		hooksInstalled,
+		worktreeClean,
+		errors
+	};
+}
+/**
+* Synchronizes configured files to the current package version.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This reads the version from `package.json` and rewrites configured files
+* using the sync patterns defined in the VersionGuard config.
+*
+* @param config - VersionGuard configuration containing sync rules.
+* @param cwd - Project directory whose files should be synchronized.
+* @example
+* ```ts
+* import { getDefaultConfig, sync } from 'versionguard';
+*
+* sync(getDefaultConfig(), process.cwd());
+* ```
+*/
+function sync(config, cwd = process.cwd()) {
+	syncVersion(getPackageVersion(cwd, config.manifest), config.sync, cwd);
+}
+/**
+* Determines whether a project can move from one version to another.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* Both the current and proposed versions must validate against the configured
+* versioning scheme, and the new version must compare greater than the current
+* version.
+*
+* @param currentVersion - Version currently in use.
+* @param newVersion - Proposed next version.
+* @param config - VersionGuard configuration that defines version rules.
+* @returns An object indicating whether the bump is allowed and why it failed.
+* @example
+* ```ts
+* import { canBump, getDefaultConfig } from 'versionguard';
+*
+* const result = canBump('1.2.3', '1.3.0', getDefaultConfig());
+* ```
+*/
+function canBump(currentVersion, newVersion, config) {
+	const currentValid = validateVersion(currentVersion, config);
+	const newValid = validateVersion(newVersion, config);
+	if (!currentValid.valid) return {
+		canBump: false,
+		error: `Current version is invalid: ${currentVersion}`
+	};
+	if (!newValid.valid) return {
+		canBump: false,
+		error: `New version is invalid: ${newVersion}`
+	};
+	if (config.versioning.type === "semver") {
+		if (!gt(newVersion, currentVersion)) return {
+			canBump: false,
+			error: `New version ${newVersion} must be greater than current ${currentVersion}`
+		};
+	} else {
+		const calverConfig = getCalVerConfig(config);
+		const currentParsed = parse$2(currentVersion, calverConfig.format);
+		const newParsed = parse$2(newVersion, calverConfig.format);
+		if (!currentParsed || !newParsed) return {
+			canBump: false,
+			error: "Failed to parse CalVer versions"
+		};
+		if (compare$1(newVersion, currentVersion, calverConfig.format) <= 0) return {
+			canBump: false,
+			error: `New CalVer ${newVersion} must be newer than current ${currentVersion}`
+		};
+	}
+	return { canBump: true };
+}
+function isWorktreeClean(cwd) {
+	try {
+		return execSync("git status --porcelain", {
+			cwd,
+			encoding: "utf-8"
+		}).trim().length === 0;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { generateDependabotConfig as $, createCkmEngine as A, detectManifests as B, suggestNextVersion as C, getVersionFeedback as D, getTagFeedback as E, syncVersion as F, RegexVersionSource as G, YamlVersionSource as H, semver_exports as I, areHooksInstalled as J, JsonVersionSource as K, getPackageVersion as L, getSemVerConfig as M, checkHardcodedVersions as N, getConfig as O, scanRepoForVersions as P, dependabotConfigExists as Q, getVersionSource as R, fixSyncIssues as S, getSyncFeedback as T, VersionFileSource as U, resolveVersionSource as V, TomlVersionSource as W, uninstallHooks as X, installHooks as Y, MANIFEST_TO_ECOSYSTEM as Z, checkHuskyBypass as _, validateVersion as a, isValidCalVerFormat as at, fixChangelog as b, getLatestTag as c, validateTagForPush as d, writeDependabotConfig as et, findProjectRoot as f, checkHooksPathOverride as g, checkHookIntegrity as h, validate as i, calver_exports as it, getCalVerConfig as j, initConfig as k, handlePostTag as l, checkEnforceHooksPolicy as m, doctor as n, isChangesetMangled as nt, createTag as o, formatNotProjectError as p, GitTagSource as q, sync as r, validateChangelog as rt, getAllTags as s, canBump as t, fixChangesetMangling as tt, suggestTagMessage as u, runGuardChecks as v, getChangelogFeedback as w, fixPackageVersion as x, fixAll as y, setPackageVersion as z };
+
+//# sourceMappingURL=src-BPMDUQfR.js.map