@codluv/versionguard 0.3.0 → 0.5.0

package/dist/index.js

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

package/dist/init-wizard.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Interactive setup wizard and headless init for VersionGuard.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for headless (non-interactive) initialization.
+ *
+ * @public
+ * @since 0.3.0
+ */
+export interface InitOptions {
+    /** Working directory path. */
+    cwd: string;
+    /** Versioning type (semver or calver). */
+    type?: 'semver' | 'calver';
+    /** CalVer format string. */
+    format?: string;
+    /** Manifest source type. */
+    manifest?: string;
+    /** Whether to install git hooks. */
+    hooks?: boolean;
+    /** Whether to enable changelog validation. */
+    changelog?: boolean;
+    /** Accept defaults without prompting. */
+    yes?: boolean;
+    /** Overwrite existing config. */
+    force?: 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.
+ *
+ * @example
+ * ```ts
+ * const configPath = await runWizard(process.cwd());
+ * ```
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * const configPath = runHeadless({ cwd: process.cwd(), type: 'calver', format: 'YYYY.M.MICRO' });
+ * ```
+ *
+ * @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,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,0CAA0C;IAC1C,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yCAAyC;IACzC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,iCAAiC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+EnE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAiBxD"}

package/dist/project-root.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Project root detection and boundary validation.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Result of project root detection.
+ *
+ * @public
+ * @since 0.4.0
+ */
+export interface ProjectRootResult {
+    /** Whether a project root was found. */
+    found: boolean;
+    /** The resolved project root directory, or the original cwd if not found. */
+    root: string;
+    /** Which marker file was found. */
+    marker?: string;
+    /** Whether the directory has a VersionGuard config. */
+    hasConfig: boolean;
+    /** Whether the directory is inside a git repository. */
+    hasGit: boolean;
+    /** Whether a version manifest file exists. */
+    hasManifest: boolean;
+}
+/**
+ * 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
+ */
+export declare function findProjectRoot(startDir: string): ProjectRootResult;
+/**
+ * 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
+ */
+export declare function formatNotProjectError(cwd: string, command: string): string;
+//# sourceMappingURL=project-root.d.ts.map

package/dist/project-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-root.d.ts","sourceRoot":"","sources":["../src/project-root.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwBH;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,SAAS,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,MAAM,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAkCnE;AA2BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAe1E"}

package/dist/project.d.ts

@@ -125,7 +125,11 @@ export declare function writePackageJson(pkg: PackageJson, cwd?: string): void;
  * ```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, manifest?: ManifestConfig): string;
@@ -149,19 +153,36 @@ export declare function getPackageVersion(cwd?: string, manifest?: ManifestConfi
  * ```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.
  *
- * @public
- * @since 0.3.0
+ * @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 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":"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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,MAAM,CAchG;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAsB,EAC3B,QAAQ,CAAC,EAAE,cAAc,GACxB,IAAI,CAWN;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EACxB,GAAG,GAAE,MAAsB,GAC1B,qBAAqB,CAEvB"}
+{"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

@@ -7,17 +7,46 @@ 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

@@ -1 +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;;;;;;;;GAQG;AACH,qBAAa,YAAa,YAAW,qBAAqB;IACxD,QAAQ,CAAC,IAAI,aAAa;IAC1B,QAAQ,CAAC,YAAY,MAAM;IAE3B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAY5B,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAc/B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAO/C"}
+{"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/json.d.ts

@@ -7,16 +7,47 @@ 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

@@ -1 +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;AAExD;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,qBAAqB;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,YAAY,GAAE,MAAuB,EAAE,WAAW,GAAE,MAAkB;IAMlF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAgB/B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAU/C"}
+{"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/regex.d.ts

@@ -9,18 +9,48 @@ 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

@@ -1 +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;;;;;;;GAOG;AACH,qBAAa,kBAAmB,YAAW,qBAAqB;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;IAiBtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAgB/B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAoB/C"}
+{"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

@@ -8,28 +8,47 @@ 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. Falls back to `package.json` if nothing
- * is detected.
- *
- * @public
- * @since 0.3.0
+ * 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.
- *
- * @public
- * @since 0.3.0
+ * 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

@@ -1 +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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,GAAE,MAAsB,GAC1B,qBAAqB,CAevB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,kBAAkB,EAAE,CAWjF"}
+{"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"}

package/dist/sources/toml.d.ts

@@ -7,19 +7,54 @@ import type { VersionSourceProvider } from './provider';
 /**
  * Reads and writes version strings from TOML manifest files.
  *
- * Uses targeted regex replacement for writes to preserve file formatting.
+ * @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
  */
 export declare class TomlVersionSource implements VersionSourceProvider {
+    /** Human-readable provider name. */
     readonly name: string;
+    /** Filename of the TOML manifest (e.g. `'Cargo.toml'`). */
     readonly manifestFile: string;
+    /** Dotted key path to the version field within the TOML document. */
     private readonly versionPath;
+    /**
+     * Creates a new TOML version source.
+     *
+     * @param manifestFile - TOML 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 TOML 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 TOML manifest, preserving formatting.
+     *
+     * @param version - Version string to write.
+     * @param cwd - Project directory containing the manifest.
+     */
     setVersion(version: string, cwd: string): void;
+    /**
+     * Splits the dotted version path into a TOML section name and key name.
+     *
+     * @returns An object with `section` and `key` components.
+     */
     private getSectionKey;
 }
 //# sourceMappingURL=toml.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"toml.d.ts","sourceRoot":"","sources":["../../src/sources/toml.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;GAOG;AACH,qBAAa,iBAAkB,YAAW,qBAAqB;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,YAAY,GAAE,MAAqB,EAAE,WAAW,GAAE,MAA0B;IAMxF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAiB/B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAkB9C,OAAO,CAAC,aAAa;CAUtB"}
+{"version":3,"file":"toml.d.ts","sourceRoot":"","sources":["../../src/sources/toml.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,YAAW,qBAAqB;IAC7D,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC;;;;;OAKG;gBACS,YAAY,GAAE,MAAqB,EAAE,WAAW,GAAE,MAA0B;IAMxF;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAiB/B;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAiB9C;;;;OAIG;IACH,OAAO,CAAC,aAAa;CAUtB"}

package/dist/sources/utils.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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
+ */
+export declare function getNestedValue(obj: Record<string, unknown>, dotPath: string): unknown;
+/**
+ * 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
+ */
+export declare function setNestedValue(obj: Record<string, unknown>, dotPath: string, value: unknown): void;
+/**
+ * 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
+ */
+export declare function escapeRegExp(value: string): string;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/sources/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CASrF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,GACb,IAAI,CAWN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD"}