@codluv/versionguard 0.2.0 → 0.4.0

package/dist/guard.d.ts

@@ -12,7 +12,11 @@ export interface GuardWarning {
     severity: 'error' | 'warning';
     /** Human-readable description of the issue. */
     message: string;
-    /** Suggested remediation command when available. */
+    /**
+     * Suggested remediation command when available.
+     *
+     * @defaultValue `undefined`
+     */
     fix?: string;
 }
 /**
@@ -37,6 +41,14 @@ export interface GuardReport {
  * @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
  */
@@ -51,6 +63,14 @@ export declare function checkHooksPathOverride(cwd: string): GuardWarning | null
  *
  * @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
  */
@@ -67,6 +87,14 @@ export declare function checkHuskyBypass(): GuardWarning | null;
  * @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
  */
@@ -81,6 +109,14 @@ export declare function checkHookIntegrity(config: VersionGuardConfig, cwd: stri
  * @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
  */
@@ -97,6 +133,14 @@ export declare function checkEnforceHooksPolicy(config: VersionGuardConfig): Gua
  * @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
  */

package/dist/guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAIlD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,IAAI,EAAE,OAAO,CAAC;IACd,yCAAyC;IACzC,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAqBvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,YAAY,GAAG,IAAI,CAWtD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAkD1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,GAAG,IAAI,CAcvF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CA2BnF"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAIlD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,IAAI,EAAE,OAAO,CAAC;IACd,yCAAyC;IACzC,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAkCvE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,IAAI,YAAY,GAAG,IAAI,CAWtD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAkD1F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,GAAG,IAAI,CAcvF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CA2BnF"}

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,QAAA,MAAM,UAAU,iDAAkD,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,GAAE,MAAsB,GAAG,IAAI,CAejF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAsB,GAAG,IAAI,CAahE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAerD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAUtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,GAAG,MAAM,CAYhF"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,QAAA,MAAM,UAAU,iDAAkD,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,GAAE,MAAsB,GAAG,IAAI,CAejF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAsB,GAAG,IAAI,CAahE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAerD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAUtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,GAAG,MAAM,CAahF"}

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * @packageDocumentation
  * @public
  */
-import type { DoctorReport, FullValidationResult, ValidationResult, VersionGuardConfig } from './types';
+import { type DoctorReport, type FullValidationResult, type ValidationResult, type VersionGuardConfig } from './types';
 export * as calver from './calver';
 export { validateChangelog } from './changelog';
 export { getConfig, initConfig } from './config';
@@ -12,8 +12,9 @@ export * from './feedback';
 export * from './fix';
 export * from './guard';
 export { areHooksInstalled, installHooks, uninstallHooks } from './hooks';
-export { getPackageVersion } from './project';
+export { getPackageVersion, getVersionSource } from './project';
 export * as semver from './semver';
+export * from './sources';
 export { checkHardcodedVersions, syncVersion } from './sync';
 export * from './tag';
 export * from './types';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,OAAO,KAAK,EAEV,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACjD,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC7D,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,gBAAgB,CAO7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,kBAAkB,EAC1B,GAAG,GAAE,MAAsB,GAC1B,oBAAoB,CAwDtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,GAAE,MAAsB,GAAG,YAAY,CA0B5F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,GAAE,MAAsB,GAAG,IAAI,CAGlF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CACrB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,kBAAkB,GACzB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAqCtC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EAEzB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACjD,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC7D,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,gBAAgB,CAY7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,kBAAkB,EAC1B,GAAG,GAAE,MAAsB,GAC1B,oBAAoB,CAwDtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,GAAE,MAAsB,GAAG,YAAY,CA0B5F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,GAAE,MAAsB,GAAG,IAAI,CAGlF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CACrB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,kBAAkB,GACzB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAqCtC"}

package/dist/index.js

@@ -1,7 +1,13 @@
 import "node:child_process";
 import "node:path";
-import { n, o, p, q, t, w, x, y, l, e, f, z, A, j, B, d, g, C, a, c, D, b, h, i, m, r, E, s, F, G, H, u, v, I, J, K } from "./chunks/index-BwE_OaV3.js";
+import { G, J, R, T, V, Y, n, o, p, q, t, w, x, y, m, z, f, j, A, B, k, C, D, e, g, E, b, d, F, c, H, h, I, a, K, r, L, s, M, N, O, u, v, P, Q, S } from "./chunks/index-B3R60bYJ.js";
 export {
+  G as GitTagSource,
+  J as JsonVersionSource,
+  R as RegexVersionSource,
+  T as TomlVersionSource,
+  V as VersionFileSource,
+  Y as YamlVersionSource,
   n as areHooksInstalled,
   o as calver,
   p as canBump,
@@ -10,33 +16,37 @@ export {
   w as checkHookIntegrity,
   x as checkHooksPathOverride,
   y as checkHuskyBypass,
-  l as createTag,
-  e as doctor,
-  f as fixAll,
-  z as fixChangelog,
-  A as fixPackageVersion,
-  j as fixSyncIssues,
-  B as getAllTags,
-  d as getChangelogFeedback,
+  m as createTag,
+  z as detectManifests,
+  f as doctor,
+  j as fixAll,
+  A as fixChangelog,
+  B as fixPackageVersion,
+  k as fixSyncIssues,
+  C as getAllTags,
+  D as getCalVerConfig,
+  e as getChangelogFeedback,
   g as getConfig,
-  C as getLatestTag,
-  a as getPackageVersion,
-  c as getSyncFeedback,
-  D as getTagFeedback,
-  b as getVersionFeedback,
+  E as getLatestTag,
+  b as getPackageVersion,
+  d as getSyncFeedback,
+  F as getTagFeedback,
+  c as getVersionFeedback,
+  H as getVersionSource,
   h as handlePostTag,
-  i as initConfig,
-  m as installHooks,
+  I as initConfig,
+  a as installHooks,
+  K as resolveVersionSource,
   r as runGuardChecks,
-  E as semver,
+  L as semver,
   s as suggestNextVersion,
-  F as suggestTagMessage,
-  G as sync,
-  H as syncVersion,
+  M as suggestTagMessage,
+  N as sync,
+  O as syncVersion,
   u as uninstallHooks,
   v as validate,
-  I as validateChangelog,
-  J as validateTagForPush,
-  K as validateVersion
+  P as validateChangelog,
+  Q as validateTagForPush,
+  S as validateVersion
 };
 //# sourceMappingURL=index.js.map

package/dist/init-wizard.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Interactive setup wizard and headless init for VersionGuard.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for headless (non-interactive) initialization.
+ *
+ * @public
+ * @since 0.3.0
+ */
+export interface InitOptions {
+    cwd: string;
+    type?: 'semver' | 'calver';
+    format?: string;
+    manifest?: string;
+    hooks?: boolean;
+    changelog?: boolean;
+    yes?: boolean;
+}
+/**
+ * Runs the interactive setup wizard.
+ *
+ * @remarks
+ * Walks the user through versioning type, CalVer format, manifest source,
+ * git hooks, and changelog configuration. Writes `.versionguard.yml` when done.
+ *
+ * @param cwd - Project directory to initialize.
+ * @returns The path to the created config file, or `null` if cancelled.
+ *
+ * @public
+ * @since 0.3.0
+ */
+export declare function runWizard(cwd: string): Promise<string | null>;
+/**
+ * Initializes VersionGuard non-interactively using CLI flags.
+ *
+ * @remarks
+ * When `--yes` is passed, all defaults are used without prompting.
+ * Individual flags override specific defaults.
+ *
+ * @param options - Headless initialization options.
+ * @returns The path to the created config file.
+ *
+ * @public
+ * @since 0.3.0
+ */
+export declare function runHeadless(options: InitOptions): string;
+//# sourceMappingURL=init-wizard.d.ts.map

package/dist/init-wizard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-wizard.d.ts","sourceRoot":"","sources":["../src/init-wizard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+EnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAexD"}

package/dist/project.d.ts

@@ -1,3 +1,5 @@
+import type { VersionSourceProvider } from './sources/provider';
+import type { ManifestConfig } from './types';
 /**
  * JSON-compatible scalar, array, or object value used by package metadata.
  *
@@ -104,41 +106,83 @@ export declare function readPackageJson(cwd?: string): PackageJson;
  */
 export declare function writePackageJson(pkg: PackageJson, cwd?: string): void;
 /**
- * Gets the version string from `package.json`.
+ * 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 file exists but does not contain a non-empty `version`
- * field.
+ * This throws when the manifest file does not exist or does not contain
+ * a version field.
  *
- * @param cwd - Project directory containing `package.json`.
- * @returns The package version string.
+ * @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' });
  * ```
  */
-export declare function getPackageVersion(cwd?: string): string;
+export declare function getPackageVersion(cwd?: string, manifest?: ManifestConfig): string;
 /**
- * Sets the version field in `package.json`.
+ * 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 full
+ * 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 `package.json`.
+ * @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' });
+ * ```
+ */
+export declare function setPackageVersion(version: string, cwd?: string, manifest?: ManifestConfig): void;
+/**
+ * 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
  */
-export declare function setPackageVersion(version: string, cwd?: string): void;
+export declare function getVersionSource(manifest: ManifestConfig, cwd?: string): VersionSourceProvider;
 //# sourceMappingURL=project.d.ts.map

package/dist/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB,OAAO,GACP,IAAI,GACJ,MAAM,GACN,MAAM,GACN,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,WAAW,CAQxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,GAAE,MAAsB,GAAG,IAAI,CAEpF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAQrE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,IAAI,CAIpF"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB,OAAO,GACP,IAAI,GACJ,MAAM,GACN,MAAM,GACN,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,WAAW,CAQxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,GAAE,MAAsB,GAAG,IAAI,CAEpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,MAAM,CAchG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAsB,EAC3B,QAAQ,CAAC,EAAE,cAAc,GACxB,IAAI,CAWN;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EACxB,GAAG,GAAE,MAAsB,GAC1B,qBAAqB,CAEvB"}

package/dist/sources/git-tag.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Git tag-based version source for Go, Swift, and similar ecosystems.
+ *
+ * @packageDocumentation
+ */
+import type { VersionSourceProvider } from './provider';
+/**
+ * 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
+ */
+export declare class GitTagSource implements VersionSourceProvider {
+    /** Human-readable provider name. */
+    readonly name = "git-tag";
+    /** Empty string since git-tag has no manifest file. */
+    readonly 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: string): boolean;
+    /**
+     * 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: string): string;
+    /**
+     * 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: string, cwd: string): void;
+    /** Try version-like tag patterns, fall back to any tag. */
+    private describeVersionTag;
+    /** Detect whether existing tags use a `v` prefix or not. */
+    private detectPrefix;
+}
+//# sourceMappingURL=git-tag.d.ts.map

package/dist/sources/git-tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-tag.d.ts","sourceRoot":"","sources":["../../src/sources/git-tag.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAa,YAAW,qBAAqB;IACxD,oCAAoC;IACpC,QAAQ,CAAC,IAAI,aAAa;IAE1B,uDAAuD;IACvD,QAAQ,CAAC,YAAY,MAAM;IAE3B;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAY5B;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAU/B;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAU9C,2DAA2D;IAC3D,OAAO,CAAC,kBAAkB;IAwB1B,4DAA4D;IAC5D,OAAO,CAAC,YAAY;CASrB"}

package/dist/sources/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Version source providers for language-agnostic manifest support.
+ *
+ * @packageDocumentation
+ * @public
+ */
+export { GitTagSource } from './git-tag';
+export { JsonVersionSource } from './json';
+export type { VersionSourceProvider } from './provider';
+export { RegexVersionSource } from './regex';
+export { detectManifests, resolveVersionSource } from './resolve';
+export { TomlVersionSource } from './toml';
+export { VersionFileSource } from './version-file';
+export { YamlVersionSource } from './yaml';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sources/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC"}

package/dist/sources/json.d.ts

@@ -0,0 +1,53 @@
+/**
+ * JSON-based version source provider for package.json and composer.json.
+ *
+ * @packageDocumentation
+ */
+import type { VersionSourceProvider } from './provider';
+/**
+ * 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
+ */
+export declare class JsonVersionSource implements VersionSourceProvider {
+    /** Human-readable provider name. */
+    readonly name: string;
+    /** Filename of the JSON manifest (e.g. `'package.json'`). */
+    readonly manifestFile: string;
+    /** Dotted key path to the version field within the JSON document. */
+    private readonly versionPath;
+    /**
+     * Creates a new JSON version source.
+     *
+     * @param manifestFile - JSON manifest filename.
+     * @param versionPath - Dotted key path to the version field.
+     */
+    constructor(manifestFile?: string, versionPath?: string);
+    /**
+     * Returns `true` when the manifest file exists in `cwd`.
+     *
+     * @param cwd - Project directory to check.
+     * @returns Whether the manifest file exists.
+     */
+    exists(cwd: string): boolean;
+    /**
+     * 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: string): string;
+    /**
+     * 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: string, cwd: string): void;
+}
+//# sourceMappingURL=json.d.ts.map

package/dist/sources/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/sources/json.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,YAAW,qBAAqB;IAC7D,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC;;;;;OAKG;gBACS,YAAY,GAAE,MAAuB,EAAE,WAAW,GAAE,MAAkB;IAMlF;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAgB/B;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAe/C"}

package/dist/sources/provider.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Version source provider interface and base utilities.
+ *
+ * @packageDocumentation
+ * @public
+ */
+/**
+ * Abstraction for reading and writing a version string from any manifest format.
+ *
+ * @public
+ * @since 0.3.0
+ */
+export interface VersionSourceProvider {
+    /** Human-readable provider name (e.g. `'package.json'`, `'Cargo.toml'`). */
+    readonly name: string;
+    /** Default manifest filename this provider handles. */
+    readonly manifestFile: string;
+    /** Returns `true` when the manifest file exists in `cwd`. */
+    exists(cwd: string): boolean;
+    /** Reads the version string from the manifest. Throws if missing or unreadable. */
+    getVersion(cwd: string): string;
+    /** Writes a version string back to the manifest. Throws if the file does not exist. */
+    setVersion(version: string, cwd: string): void;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/sources/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/sources/provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,uDAAuD;IACvD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,6DAA6D;IAC7D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE7B,mFAAmF;IACnF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAEhC,uFAAuF;IACvF,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAChD"}

package/dist/sources/regex.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Regex-based version source for source-code manifests.
+ *
+ * Handles gemspec, mix.exs, setup.py, build.gradle, etc.
+ *
+ * @packageDocumentation
+ */
+import type { VersionSourceProvider } from './provider';
+/**
+ * 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
+ */
+export declare class RegexVersionSource implements VersionSourceProvider {
+    /** Human-readable provider name. */
+    readonly name: string;
+    /** Filename of the source manifest (e.g. `'setup.py'`). */
+    readonly manifestFile: string;
+    /** Compiled regex used to locate the version string. */
+    private readonly 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: string, versionRegex: string);
+    /**
+     * Returns `true` when the manifest file exists in `cwd`.
+     *
+     * @param cwd - Project directory to check.
+     * @returns Whether the manifest file exists.
+     */
+    exists(cwd: string): boolean;
+    /**
+     * 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: string): string;
+    /**
+     * 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: string, cwd: string): void;
+}
+//# sourceMappingURL=regex.d.ts.map

package/dist/sources/regex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regex.d.ts","sourceRoot":"","sources":["../../src/sources/regex.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,YAAW,qBAAqB;IAC9D,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;;;;OAKG;gBACS,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;IAiBtD;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAgB/B;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAoB/C"}

package/dist/sources/resolve.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Version source auto-detection and resolution.
+ *
+ * @packageDocumentation
+ */
+import type { ManifestConfig, ManifestSourceType } from '../types';
+import type { VersionSourceProvider } from './provider';
+/**
+ * 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
+ */
+export declare function resolveVersionSource(config: ManifestConfig, cwd?: string): VersionSourceProvider;
+/**
+ * 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
+ */
+export declare function detectManifests(cwd?: string): ManifestSourceType[];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/sources/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/sources/resolve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAGnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAiIxD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,GAAE,MAAsB,GAC1B,qBAAqB,CAoBvB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,kBAAkB,EAAE,CAWjF"}