package-versioner 0.8.3 → 0.8.5

package/README.md

@@ -55,6 +55,9 @@ npx package-versioner --bump patch --prerelease alpha
 # Target specific packages (only in async/independent mode, comma-separated)
 npx package-versioner -t @scope/package-a,@scope/package-b
 
+# Run from a different directory
+npx package-versioner --project-dir /path/to/project
+
 # Perform a dry run: calculates version, logs actions, but makes no file changes or Git commits/tags
 npx package-versioner --dry-run
 
@@ -159,7 +162,7 @@ Customize behaviour by creating a `version.config.json` file in your project roo
 #### Monorepo-Specific Options
 - `synced`: Whether all packages should be versioned together (default: true)
 - `skip`: Array of package names or patterns to exclude from versioning. Supports exact names, scope wildcards, path patterns, and global wildcards (e.g., ["@scope/package-a", "@scope/*", "packages/**/*"])
-- `packages`: Array of package names or patterns to target for versioning. Supports exact names, scope wildcards, and global wildcards (e.g., ["@scope/package-a", "@scope/*", "*"])
+- `packages`: Array of package names or patterns to target for versioning. Supports exact names, scope wildcards, path patterns and global wildcards (e.g., ["@scope/package-a", "@scope/*", "*"])
 - `mainPackage`: Package name whose commit history should drive version determination
 - `packageSpecificTags`: Whether to enable package-specific tagging behaviour (default: false)
 - `updateInternalDependencies`: How to update internal dependencies ("patch", "minor", "major", or "inherit")
@@ -185,6 +188,15 @@ Target all packages within a specific scope:
 }
 ```
 
+#### Path Patterns / Globs
+Target all packages in a directory or matching a path pattern:
+```json
+{
+  "packages": ["packages/**/*", "examples/**"]
+}
+```
+This will match all packages in nested directories under `packages/` or `examples/`.
+
 #### Global Wildcard
 Target all packages in the workspace:
 ```json
@@ -197,7 +209,7 @@ Target all packages in the workspace:
 Combine different pattern types:
 ```json
 {
-  "packages": ["@mycompany/*", "@utils/logger", "legacy-package"]
+  "packages": ["@mycompany/*", "@utils/logger", "legacy-package", "packages/**/*"]
 }
 ```
 

package/dist/index.cjs

@@ -759,7 +759,7 @@ function matchesPackageNamePattern(packageName, pattern) {
 }
 
 // src/core/versionStrategies.ts
-var import_node_child_process5 = require("child_process");
+var import_node_child_process4 = require("child_process");
 var import_node_fs7 = __toESM(require("fs"), 1);
 var path8 = __toESM(require("path"), 1);
 
@@ -1041,9 +1041,14 @@ function formatCommitMessage(template, version, packageName, additionalContext)
 }
 
 // src/git/tagsAndBranches.ts
-function getCommitsLength(pkgRoot) {
+function getCommitsLength(pkgRoot, sinceTag) {
   try {
-    const gitCommand = `git rev-list --count HEAD ^$(git describe --tags --abbrev=0) ${pkgRoot}`;
+    let gitCommand;
+    if (sinceTag && sinceTag.trim() !== "") {
+      gitCommand = `git rev-list --count ${sinceTag}..HEAD ${pkgRoot}`;
+    } else {
+      gitCommand = `git rev-list --count HEAD ^$(git describe --tags --abbrev=0) ${pkgRoot}`;
+    }
     const amount = execSync3(gitCommand).toString().trim();
     return Number(amount);
   } catch (error) {
@@ -1317,7 +1322,6 @@ function updatePackageVersion(packagePath, version) {
 }
 
 // src/package/packageProcessor.ts
-var import_node_child_process4 = require("child_process");
 var fs8 = __toESM(require("fs"), 1);
 var import_node_path7 = __toESM(require("path"), 1);
 var import_node_process4 = require("process");
@@ -1376,18 +1380,41 @@ function getVersionFromManifests(packageDir) {
     manifestType: null
   };
 }
-function throwIfNoManifestsFound(packageDir) {
-  const packageJsonPath = import_node_path6.default.join(packageDir, "package.json");
-  const cargoTomlPath = import_node_path6.default.join(packageDir, "Cargo.toml");
-  throw new Error(
-    `Neither package.json nor Cargo.toml found at ${packageDir}. Checked paths: ${packageJsonPath}, ${cargoTomlPath}. Cannot determine version.`
-  );
-}
 
 // src/utils/versionUtils.ts
 var import_node_fs6 = __toESM(require("fs"), 1);
 var import_semver2 = __toESM(require("semver"), 1);
 var TOML2 = __toESM(require("smol-toml"), 1);
+
+// src/git/tagVerification.ts
+function verifyTag(tagName, cwd5) {
+  if (!tagName || tagName.trim() === "") {
+    return { exists: false, reachable: false, error: "Empty tag name" };
+  }
+  try {
+    execSync3(`git rev-parse --verify "${tagName}"`, {
+      cwd: cwd5,
+      stdio: "ignore"
+    });
+    return { exists: true, reachable: true };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (errorMessage.includes("unknown revision") || errorMessage.includes("bad revision") || errorMessage.includes("No such ref")) {
+      return {
+        exists: false,
+        reachable: false,
+        error: `Tag '${tagName}' not found in repository`
+      };
+    }
+    return {
+      exists: false,
+      reachable: false,
+      error: `Git error: ${errorMessage}`
+    };
+  }
+}
+
+// src/utils/versionUtils.ts
 var STANDARD_BUMP_TYPES = ["major", "minor", "patch"];
 function normalizePrereleaseIdentifier(prereleaseIdentifier, config) {
   if (prereleaseIdentifier === true) {
@@ -1421,6 +1448,59 @@ function bumpVersion(currentVersion, bumpType, prereleaseIdentifier) {
   }
   return import_semver2.default.inc(currentVersion, bumpType, prereleaseIdentifier) || "";
 }
+async function getBestVersionSource(tagName, packageVersion, cwd5) {
+  if (!(tagName == null ? void 0 : tagName.trim())) {
+    return packageVersion ? { source: "package", version: packageVersion, reason: "No git tag provided" } : { source: "initial", version: "0.1.0", reason: "No git tag or package version available" };
+  }
+  const verification = verifyTag(tagName, cwd5);
+  if (!verification.exists || !verification.reachable) {
+    if (packageVersion) {
+      log(
+        `Git tag '${tagName}' unreachable (${verification.error}), using package version: ${packageVersion}`,
+        "warning"
+      );
+      return { source: "package", version: packageVersion, reason: "Git tag unreachable" };
+    }
+    log(
+      `Git tag '${tagName}' unreachable and no package version available, using initial version`,
+      "warning"
+    );
+    return {
+      source: "initial",
+      version: "0.1.0",
+      reason: "Git tag unreachable, no package version"
+    };
+  }
+  if (!packageVersion) {
+    return {
+      source: "git",
+      version: tagName,
+      reason: "Git tag exists, no package version to compare"
+    };
+  }
+  try {
+    const cleanTagVersion = tagName.replace(/^.*?([0-9])/, "$1");
+    const cleanPackageVersion = packageVersion;
+    if (import_semver2.default.gt(cleanPackageVersion, cleanTagVersion)) {
+      log(
+        `Package version ${packageVersion} is newer than git tag ${tagName}, using package version`,
+        "info"
+      );
+      return { source: "package", version: packageVersion, reason: "Package version is newer" };
+    }
+    if (import_semver2.default.gt(cleanTagVersion, cleanPackageVersion)) {
+      log(
+        `Git tag ${tagName} is newer than package version ${packageVersion}, using git tag`,
+        "info"
+      );
+      return { source: "git", version: tagName, reason: "Git tag is newer" };
+    }
+    return { source: "git", version: tagName, reason: "Versions equal, using git tag" };
+  } catch (error) {
+    log(`Failed to compare versions, defaulting to git tag: ${error}`, "warning");
+    return { source: "git", version: tagName, reason: "Version comparison failed" };
+  }
+}
 
 // src/core/versionCalculator.ts
 async function calculateVersion(config, options) {
@@ -1452,76 +1532,35 @@ async function calculateVersion(config, options) {
       return `${packageName}@${prefix}`;
     }, escapeRegExp3 = function(string) {
       return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }, getCurrentVersionFromSource2 = function() {
+      if (!versionSource) {
+        if (hasNoTags) {
+          return initialVersion;
+        }
+        const cleanedTag = import_semver3.default.clean(latestTag) || latestTag;
+        return import_semver3.default.clean(cleanedTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
+      }
+      if (versionSource.source === "git") {
+        const cleanedTag = import_semver3.default.clean(versionSource.version) || versionSource.version;
+        return import_semver3.default.clean(cleanedTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
+      }
+      return versionSource.version;
     };
-    var determineTagSearchPattern = determineTagSearchPattern2, escapeRegExp2 = escapeRegExp3;
+    var determineTagSearchPattern = determineTagSearchPattern2, escapeRegExp2 = escapeRegExp3, getCurrentVersionFromSource = getCurrentVersionFromSource2;
     const originalPrefix = versionPrefix || "";
     const tagSearchPattern = determineTagSearchPattern2(name, originalPrefix);
     const escapedTagPattern = escapeRegExp3(tagSearchPattern);
-    if (!hasNoTags && pkgPath) {
+    let versionSource;
+    if (pkgPath) {
       const packageDir = pkgPath || (0, import_node_process3.cwd)();
       const manifestResult = getVersionFromManifests(packageDir);
-      if (manifestResult.manifestFound && manifestResult.version) {
-        const cleanedTag = import_semver3.default.clean(latestTag) || latestTag;
-        const tagVersion = import_semver3.default.clean(cleanedTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
-        const packageVersion = manifestResult.version;
-        if (import_semver3.default.gt(packageVersion, tagVersion)) {
-          log(
-            `Warning: Version mismatch detected!
-\u2022 ${manifestResult.manifestType} version: ${packageVersion}
-\u2022 Latest Git tag version: ${tagVersion} (from ${latestTag})
-\u2022 Package version is AHEAD of Git tags
-
-This usually happens when:
-\u2022 A version was released but the tag wasn't pushed to the remote repository
-\u2022 The ${manifestResult.manifestType} was manually updated without creating a corresponding tag
-\u2022 You're running in CI and the latest tag isn't available yet
-
-The tool will use the Git tag version (${tagVersion}) as the base for calculation.
-Expected next version will be based on ${tagVersion}, not ${packageVersion}.
-
-To fix this mismatch:
-\u2022 Push missing tags: git push origin --tags
-\u2022 Or use package version as base by ensuring tags are up to date`,
-            "warning"
-          );
-        } else if (import_semver3.default.gt(tagVersion, packageVersion)) {
-          log(
-            `Warning: Version mismatch detected!
-\u2022 ${manifestResult.manifestType} version: ${packageVersion}
-\u2022 Latest Git tag version: ${tagVersion} (from ${latestTag})
-\u2022 Git tag version is AHEAD of package version
-
-This usually happens when:
-\u2022 A release was tagged but the ${manifestResult.manifestType} wasn't updated
-\u2022 You're on an older branch that hasn't been updated with the latest version
-\u2022 Automated release process created tags but didn't update manifest files
-\u2022 You pulled tags but not the corresponding commits that update the package version
-
-The tool will use the Git tag version (${tagVersion}) as the base for calculation.
-This will likely result in a version that's already been released.
-
-To fix this mismatch:
-\u2022 Update ${manifestResult.manifestType}: Set version to ${tagVersion} or higher
-\u2022 Or checkout the branch/commit that corresponds to the tag
-\u2022 Or ensure your branch is up to date with the latest changes`,
-            "warning"
-          );
-        }
-      }
+      const packageVersion = manifestResult.manifestFound && manifestResult.version ? manifestResult.version : void 0;
+      versionSource = await getBestVersionSource(latestTag, packageVersion, packageDir);
+      log(`Using version source: ${versionSource.source} (${versionSource.reason})`, "info");
     }
     const specifiedType = type;
     if (specifiedType) {
-      if (hasNoTags) {
-        return getPackageVersionFallback(
-          pkgPath,
-          name,
-          specifiedType,
-          normalizedPrereleaseId,
-          initialVersion
-        );
-      }
-      const cleanedTag = import_semver3.default.clean(latestTag) || latestTag;
-      const currentVersion = import_semver3.default.clean(cleanedTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
+      const currentVersion = getCurrentVersionFromSource2();
       if (STANDARD_BUMP_TYPES.includes(specifiedType) && (import_semver3.default.prerelease(currentVersion) || normalizedPrereleaseId)) {
         log(
           normalizedPrereleaseId ? `Creating prerelease version with identifier '${normalizedPrereleaseId}' using ${specifiedType}` : `Cleaning prerelease identifier from ${currentVersion} for ${specifiedType} bump`,
@@ -1551,17 +1590,7 @@ To fix this mismatch:
         }
       }
       if (branchVersionType) {
-        if (hasNoTags) {
-          return getPackageVersionFallback(
-            pkgPath,
-            name,
-            branchVersionType,
-            normalizedPrereleaseId,
-            initialVersion
-          );
-        }
-        const cleanedTag = import_semver3.default.clean(latestTag) || latestTag;
-        const currentVersion = import_semver3.default.clean(cleanedTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
+        const currentVersion = getCurrentVersionFromSource2();
         log(`Applying ${branchVersionType} bump based on branch pattern`, "debug");
         return bumpVersion(currentVersion, branchVersionType, normalizedPrereleaseId);
       }
@@ -1571,35 +1600,34 @@ To fix this mismatch:
       bumper.loadPreset(preset);
       const recommendedBump = await bumper.bump();
       const releaseTypeFromCommits = recommendedBump && "releaseType" in recommendedBump ? recommendedBump.releaseType : void 0;
-      if (hasNoTags) {
-        if (releaseTypeFromCommits) {
-          return getPackageVersionFallback(
-            pkgPath,
-            name,
-            releaseTypeFromCommits,
-            normalizedPrereleaseId,
-            initialVersion
+      const currentVersion = getCurrentVersionFromSource2();
+      if (versionSource && versionSource.source === "git") {
+        const checkPath = pkgPath || (0, import_node_process3.cwd)();
+        const commitsLength = getCommitsLength(checkPath, versionSource.version);
+        if (commitsLength === 0) {
+          log(
+            `No new commits found for ${name || "project"} since ${versionSource.version}, skipping version bump`,
+            "info"
           );
+          return "";
         }
-        return initialVersion;
-      }
-      const checkPath = pkgPath || (0, import_node_process3.cwd)();
-      const commitsLength = getCommitsLength(checkPath);
-      if (commitsLength === 0) {
+      } else if (versionSource && versionSource.source === "package") {
         log(
-          `No new commits found for ${name || "project"} since ${latestTag}, skipping version bump`,
-          "info"
+          `Using package version ${versionSource.version} as base, letting conventional commits determine bump necessity`,
+          "debug"
         );
-        return "";
       }
       if (!releaseTypeFromCommits) {
-        log(
-          `No relevant commits found for ${name || "project"} since ${latestTag}, skipping version bump`,
-          "info"
-        );
+        if (latestTag && latestTag.trim() !== "") {
+          log(
+            `No relevant commits found for ${name || "project"} since ${latestTag}, skipping version bump`,
+            "info"
+          );
+        } else {
+          log(`No relevant commits found for ${name || "project"}, skipping version bump`, "info");
+        }
         return "";
       }
-      const currentVersion = import_semver3.default.clean(latestTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
       return bumpVersion(currentVersion, releaseTypeFromCommits, normalizedPrereleaseId);
     } catch (error) {
       log(`Failed to calculate version for ${name || "project"}`, "error");
@@ -1620,40 +1648,6 @@ To fix this mismatch:
     throw error;
   }
 }
-function getPackageVersionFallback(pkgPath, name, releaseType, prereleaseIdentifier, initialVersion) {
-  const packageDir = pkgPath || (0, import_node_process3.cwd)();
-  const manifestResult = getVersionFromManifests(packageDir);
-  if (manifestResult.manifestFound && manifestResult.version) {
-    log(
-      `No tags found for ${name || "package"}, using ${manifestResult.manifestType} version: ${manifestResult.version} as base`,
-      "info"
-    );
-    return calculateNextVersion(
-      manifestResult.version,
-      manifestResult.manifestType || "manifest",
-      name,
-      releaseType,
-      prereleaseIdentifier,
-      initialVersion
-    );
-  }
-  throwIfNoManifestsFound(packageDir);
-}
-function calculateNextVersion(version, manifestType, name, releaseType, prereleaseIdentifier, initialVersion) {
-  log(
-    `No tags found for ${name || "package"}, using ${manifestType} version: ${version} as base`,
-    "info"
-  );
-  if (STANDARD_BUMP_TYPES.includes(releaseType) && (import_semver3.default.prerelease(version) || prereleaseIdentifier)) {
-    log(
-      prereleaseIdentifier ? `Creating prerelease version with identifier '${prereleaseIdentifier}' using ${releaseType}` : `Cleaning prerelease identifier from ${version} for ${releaseType} bump`,
-      "debug"
-    );
-    return bumpVersion(version, releaseType, prereleaseIdentifier);
-  }
-  const result = bumpVersion(version, releaseType, prereleaseIdentifier);
-  return result || initialVersion;
-}
 
 // src/utils/packageMatching.ts
 var import_micromatch2 = __toESM(require("micromatch"), 1);
@@ -1803,14 +1797,14 @@ var PackageProcessor = class {
         try {
           let revisionRange;
           if (latestTag) {
-            try {
-              (0, import_node_child_process4.execSync)(`git rev-parse --verify "${latestTag}"`, {
-                cwd: pkgPath,
-                stdio: "ignore"
-              });
+            const verification = verifyTag(latestTag, pkgPath);
+            if (verification.exists && verification.reachable) {
               revisionRange = `${latestTag}..HEAD`;
-            } catch {
-              log(`Tag ${latestTag} doesn't exist, using all commits for changelog`, "debug");
+            } else {
+              log(
+                `Tag ${latestTag} is unreachable (${verification.error}), using all commits for changelog`,
+                "debug"
+              );
               revisionRange = "HEAD";
             }
           } else {
@@ -1999,7 +1993,7 @@ function createSyncedStrategy(config) {
         mainPackage
       } = config;
       const formattedPrefix = formatVersionPrefix(versionPrefix || "v");
-      const latestTag = await getLatestTag();
+      let latestTag = await getLatestTag();
       let mainPkgPath = packages.root;
       let mainPkgName;
       if (mainPackage) {
@@ -2022,6 +2016,21 @@ function createSyncedStrategy(config) {
           "warning"
         );
       }
+      if (mainPkgName) {
+        const packageSpecificTag = await getLatestTagForPackage(mainPkgName, formattedPrefix, {
+          tagTemplate,
+          packageSpecificTags: config.packageSpecificTags
+        });
+        if (packageSpecificTag) {
+          latestTag = packageSpecificTag;
+          log(`Using package-specific tag for ${mainPkgName}: ${latestTag}`, "debug");
+        } else {
+          log(
+            `No package-specific tag found for ${mainPkgName}, using global tag: ${latestTag}`,
+            "debug"
+          );
+        }
+      }
       const nextVersion = await calculateVersion(config, {
         latestTag,
         versionPrefix: formattedPrefix,
@@ -2164,7 +2173,7 @@ function createSingleStrategy(config) {
           let revisionRange;
           if (latestTag) {
             try {
-              (0, import_node_child_process5.execSync)(`git rev-parse --verify "${latestTag}"`, {
+              (0, import_node_child_process4.execSync)(`git rev-parse --verify "${latestTag}"`, {
                 cwd: pkgPath,
                 stdio: "ignore"
               });
@@ -2451,11 +2460,22 @@ async function run() {
     program.command("version", { isDefault: true }).description("Version a package or packages based on configuration").option(
       "-c, --config <path>",
       "Path to config file (defaults to version.config.json in current directory)"
-    ).option("-d, --dry-run", "Dry run (no changes made)", false).option("-b, --bump <type>", "Specify bump type (patch|minor|major)").option("-p, --prerelease [identifier]", "Create prerelease version").option("-s, --synced", "Use synchronized versioning across all packages").option("-j, --json", "Output results as JSON", false).option("-t, --target <packages>", "Comma-delimited list of package names to target").action(async (options) => {
+    ).option("-d, --dry-run", "Dry run (no changes made)", false).option("-b, --bump <type>", "Specify bump type (patch|minor|major)").option("-p, --prerelease [identifier]", "Create prerelease version").option("-s, --synced", "Use synchronized versioning across all packages").option("-j, --json", "Output results as JSON", false).option("-t, --target <packages>", "Comma-delimited list of package names to target").option("--project-dir <path>", "Project directory to run commands in", process.cwd()).action(async (options) => {
       if (options.json) {
         enableJsonOutput(options.dryRun);
       }
       try {
+        const originalCwd = process.cwd();
+        if (options.projectDir && options.projectDir !== originalCwd) {
+          try {
+            process.chdir(options.projectDir);
+            log(`Changed working directory to: ${options.projectDir}`, "debug");
+          } catch (error) {
+            throw new Error(
+              `Failed to change to directory "${options.projectDir}": ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+        }
         const config = await loadConfig(options.config);
         log(`Loaded configuration from ${options.config || "version.config.json"}`, "info");
         if (options.dryRun) config.dryRun = true;

package/dist/index.js

@@ -726,7 +726,7 @@ function matchesPackageNamePattern(packageName, pattern) {
 }
 
 // src/core/versionStrategies.ts
-import { execSync as execSync5 } from "child_process";
+import { execSync as execSync4 } from "child_process";
 import fs9 from "fs";
 import * as path8 from "path";
 
@@ -1008,9 +1008,14 @@ function formatCommitMessage(template, version, packageName, additionalContext)
 }
 
 // src/git/tagsAndBranches.ts
-function getCommitsLength(pkgRoot) {
+function getCommitsLength(pkgRoot, sinceTag) {
   try {
-    const gitCommand = `git rev-list --count HEAD ^$(git describe --tags --abbrev=0) ${pkgRoot}`;
+    let gitCommand;
+    if (sinceTag && sinceTag.trim() !== "") {
+      gitCommand = `git rev-list --count ${sinceTag}..HEAD ${pkgRoot}`;
+    } else {
+      gitCommand = `git rev-list --count HEAD ^$(git describe --tags --abbrev=0) ${pkgRoot}`;
+    }
     const amount = execSync3(gitCommand).toString().trim();
     return Number(amount);
   } catch (error) {
@@ -1284,7 +1289,6 @@ function updatePackageVersion(packagePath, version) {
 }
 
 // src/package/packageProcessor.ts
-import { execSync as execSync4 } from "child_process";
 import * as fs8 from "fs";
 import path7 from "path";
 import { exit } from "process";
@@ -1343,18 +1347,41 @@ function getVersionFromManifests(packageDir) {
     manifestType: null
   };
 }
-function throwIfNoManifestsFound(packageDir) {
-  const packageJsonPath = path6.join(packageDir, "package.json");
-  const cargoTomlPath = path6.join(packageDir, "Cargo.toml");
-  throw new Error(
-    `Neither package.json nor Cargo.toml found at ${packageDir}. Checked paths: ${packageJsonPath}, ${cargoTomlPath}. Cannot determine version.`
-  );
-}
 
 // src/utils/versionUtils.ts
 import fs7 from "fs";
 import semver2 from "semver";
 import * as TOML2 from "smol-toml";
+
+// src/git/tagVerification.ts
+function verifyTag(tagName, cwd5) {
+  if (!tagName || tagName.trim() === "") {
+    return { exists: false, reachable: false, error: "Empty tag name" };
+  }
+  try {
+    execSync3(`git rev-parse --verify "${tagName}"`, {
+      cwd: cwd5,
+      stdio: "ignore"
+    });
+    return { exists: true, reachable: true };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (errorMessage.includes("unknown revision") || errorMessage.includes("bad revision") || errorMessage.includes("No such ref")) {
+      return {
+        exists: false,
+        reachable: false,
+        error: `Tag '${tagName}' not found in repository`
+      };
+    }
+    return {
+      exists: false,
+      reachable: false,
+      error: `Git error: ${errorMessage}`
+    };
+  }
+}
+
+// src/utils/versionUtils.ts
 var STANDARD_BUMP_TYPES = ["major", "minor", "patch"];
 function normalizePrereleaseIdentifier(prereleaseIdentifier, config) {
   if (prereleaseIdentifier === true) {
@@ -1388,6 +1415,59 @@ function bumpVersion(currentVersion, bumpType, prereleaseIdentifier) {
   }
   return semver2.inc(currentVersion, bumpType, prereleaseIdentifier) || "";
 }
+async function getBestVersionSource(tagName, packageVersion, cwd5) {
+  if (!(tagName == null ? void 0 : tagName.trim())) {
+    return packageVersion ? { source: "package", version: packageVersion, reason: "No git tag provided" } : { source: "initial", version: "0.1.0", reason: "No git tag or package version available" };
+  }
+  const verification = verifyTag(tagName, cwd5);
+  if (!verification.exists || !verification.reachable) {
+    if (packageVersion) {
+      log(
+        `Git tag '${tagName}' unreachable (${verification.error}), using package version: ${packageVersion}`,
+        "warning"
+      );
+      return { source: "package", version: packageVersion, reason: "Git tag unreachable" };
+    }
+    log(
+      `Git tag '${tagName}' unreachable and no package version available, using initial version`,
+      "warning"
+    );
+    return {
+      source: "initial",
+      version: "0.1.0",
+      reason: "Git tag unreachable, no package version"
+    };
+  }
+  if (!packageVersion) {
+    return {
+      source: "git",
+      version: tagName,
+      reason: "Git tag exists, no package version to compare"
+    };
+  }
+  try {
+    const cleanTagVersion = tagName.replace(/^.*?([0-9])/, "$1");
+    const cleanPackageVersion = packageVersion;
+    if (semver2.gt(cleanPackageVersion, cleanTagVersion)) {
+      log(
+        `Package version ${packageVersion} is newer than git tag ${tagName}, using package version`,
+        "info"
+      );
+      return { source: "package", version: packageVersion, reason: "Package version is newer" };
+    }
+    if (semver2.gt(cleanTagVersion, cleanPackageVersion)) {
+      log(
+        `Git tag ${tagName} is newer than package version ${packageVersion}, using git tag`,
+        "info"
+      );
+      return { source: "git", version: tagName, reason: "Git tag is newer" };
+    }
+    return { source: "git", version: tagName, reason: "Versions equal, using git tag" };
+  } catch (error) {
+    log(`Failed to compare versions, defaulting to git tag: ${error}`, "warning");
+    return { source: "git", version: tagName, reason: "Version comparison failed" };
+  }
+}
 
 // src/core/versionCalculator.ts
 async function calculateVersion(config, options) {
@@ -1419,76 +1499,35 @@ async function calculateVersion(config, options) {
       return `${packageName}@${prefix}`;
     }, escapeRegExp3 = function(string) {
       return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }, getCurrentVersionFromSource2 = function() {
+      if (!versionSource) {
+        if (hasNoTags) {
+          return initialVersion;
+        }
+        const cleanedTag = semver3.clean(latestTag) || latestTag;
+        return semver3.clean(cleanedTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
+      }
+      if (versionSource.source === "git") {
+        const cleanedTag = semver3.clean(versionSource.version) || versionSource.version;
+        return semver3.clean(cleanedTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
+      }
+      return versionSource.version;
     };
-    var determineTagSearchPattern = determineTagSearchPattern2, escapeRegExp2 = escapeRegExp3;
+    var determineTagSearchPattern = determineTagSearchPattern2, escapeRegExp2 = escapeRegExp3, getCurrentVersionFromSource = getCurrentVersionFromSource2;
     const originalPrefix = versionPrefix || "";
     const tagSearchPattern = determineTagSearchPattern2(name, originalPrefix);
     const escapedTagPattern = escapeRegExp3(tagSearchPattern);
-    if (!hasNoTags && pkgPath) {
+    let versionSource;
+    if (pkgPath) {
       const packageDir = pkgPath || cwd3();
       const manifestResult = getVersionFromManifests(packageDir);
-      if (manifestResult.manifestFound && manifestResult.version) {
-        const cleanedTag = semver3.clean(latestTag) || latestTag;
-        const tagVersion = semver3.clean(cleanedTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
-        const packageVersion = manifestResult.version;
-        if (semver3.gt(packageVersion, tagVersion)) {
-          log(
-            `Warning: Version mismatch detected!
-\u2022 ${manifestResult.manifestType} version: ${packageVersion}
-\u2022 Latest Git tag version: ${tagVersion} (from ${latestTag})
-\u2022 Package version is AHEAD of Git tags
-
-This usually happens when:
-\u2022 A version was released but the tag wasn't pushed to the remote repository
-\u2022 The ${manifestResult.manifestType} was manually updated without creating a corresponding tag
-\u2022 You're running in CI and the latest tag isn't available yet
-
-The tool will use the Git tag version (${tagVersion}) as the base for calculation.
-Expected next version will be based on ${tagVersion}, not ${packageVersion}.
-
-To fix this mismatch:
-\u2022 Push missing tags: git push origin --tags
-\u2022 Or use package version as base by ensuring tags are up to date`,
-            "warning"
-          );
-        } else if (semver3.gt(tagVersion, packageVersion)) {
-          log(
-            `Warning: Version mismatch detected!
-\u2022 ${manifestResult.manifestType} version: ${packageVersion}
-\u2022 Latest Git tag version: ${tagVersion} (from ${latestTag})
-\u2022 Git tag version is AHEAD of package version
-
-This usually happens when:
-\u2022 A release was tagged but the ${manifestResult.manifestType} wasn't updated
-\u2022 You're on an older branch that hasn't been updated with the latest version
-\u2022 Automated release process created tags but didn't update manifest files
-\u2022 You pulled tags but not the corresponding commits that update the package version
-
-The tool will use the Git tag version (${tagVersion}) as the base for calculation.
-This will likely result in a version that's already been released.
-
-To fix this mismatch:
-\u2022 Update ${manifestResult.manifestType}: Set version to ${tagVersion} or higher
-\u2022 Or checkout the branch/commit that corresponds to the tag
-\u2022 Or ensure your branch is up to date with the latest changes`,
-            "warning"
-          );
-        }
-      }
+      const packageVersion = manifestResult.manifestFound && manifestResult.version ? manifestResult.version : void 0;
+      versionSource = await getBestVersionSource(latestTag, packageVersion, packageDir);
+      log(`Using version source: ${versionSource.source} (${versionSource.reason})`, "info");
     }
     const specifiedType = type;
     if (specifiedType) {
-      if (hasNoTags) {
-        return getPackageVersionFallback(
-          pkgPath,
-          name,
-          specifiedType,
-          normalizedPrereleaseId,
-          initialVersion
-        );
-      }
-      const cleanedTag = semver3.clean(latestTag) || latestTag;
-      const currentVersion = semver3.clean(cleanedTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
+      const currentVersion = getCurrentVersionFromSource2();
       if (STANDARD_BUMP_TYPES.includes(specifiedType) && (semver3.prerelease(currentVersion) || normalizedPrereleaseId)) {
         log(
           normalizedPrereleaseId ? `Creating prerelease version with identifier '${normalizedPrereleaseId}' using ${specifiedType}` : `Cleaning prerelease identifier from ${currentVersion} for ${specifiedType} bump`,
@@ -1518,17 +1557,7 @@ To fix this mismatch:
         }
       }
       if (branchVersionType) {
-        if (hasNoTags) {
-          return getPackageVersionFallback(
-            pkgPath,
-            name,
-            branchVersionType,
-            normalizedPrereleaseId,
-            initialVersion
-          );
-        }
-        const cleanedTag = semver3.clean(latestTag) || latestTag;
-        const currentVersion = semver3.clean(cleanedTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
+        const currentVersion = getCurrentVersionFromSource2();
         log(`Applying ${branchVersionType} bump based on branch pattern`, "debug");
         return bumpVersion(currentVersion, branchVersionType, normalizedPrereleaseId);
       }
@@ -1538,35 +1567,34 @@ To fix this mismatch:
       bumper.loadPreset(preset);
       const recommendedBump = await bumper.bump();
       const releaseTypeFromCommits = recommendedBump && "releaseType" in recommendedBump ? recommendedBump.releaseType : void 0;
-      if (hasNoTags) {
-        if (releaseTypeFromCommits) {
-          return getPackageVersionFallback(
-            pkgPath,
-            name,
-            releaseTypeFromCommits,
-            normalizedPrereleaseId,
-            initialVersion
+      const currentVersion = getCurrentVersionFromSource2();
+      if (versionSource && versionSource.source === "git") {
+        const checkPath = pkgPath || cwd3();
+        const commitsLength = getCommitsLength(checkPath, versionSource.version);
+        if (commitsLength === 0) {
+          log(
+            `No new commits found for ${name || "project"} since ${versionSource.version}, skipping version bump`,
+            "info"
           );
+          return "";
         }
-        return initialVersion;
-      }
-      const checkPath = pkgPath || cwd3();
-      const commitsLength = getCommitsLength(checkPath);
-      if (commitsLength === 0) {
+      } else if (versionSource && versionSource.source === "package") {
         log(
-          `No new commits found for ${name || "project"} since ${latestTag}, skipping version bump`,
-          "info"
+          `Using package version ${versionSource.version} as base, letting conventional commits determine bump necessity`,
+          "debug"
         );
-        return "";
       }
       if (!releaseTypeFromCommits) {
-        log(
-          `No relevant commits found for ${name || "project"} since ${latestTag}, skipping version bump`,
-          "info"
-        );
+        if (latestTag && latestTag.trim() !== "") {
+          log(
+            `No relevant commits found for ${name || "project"} since ${latestTag}, skipping version bump`,
+            "info"
+          );
+        } else {
+          log(`No relevant commits found for ${name || "project"}, skipping version bump`, "info");
+        }
         return "";
       }
-      const currentVersion = semver3.clean(latestTag.replace(new RegExp(`^${escapedTagPattern}`), "")) || "0.0.0";
       return bumpVersion(currentVersion, releaseTypeFromCommits, normalizedPrereleaseId);
     } catch (error) {
       log(`Failed to calculate version for ${name || "project"}`, "error");
@@ -1587,40 +1615,6 @@ To fix this mismatch:
     throw error;
   }
 }
-function getPackageVersionFallback(pkgPath, name, releaseType, prereleaseIdentifier, initialVersion) {
-  const packageDir = pkgPath || cwd3();
-  const manifestResult = getVersionFromManifests(packageDir);
-  if (manifestResult.manifestFound && manifestResult.version) {
-    log(
-      `No tags found for ${name || "package"}, using ${manifestResult.manifestType} version: ${manifestResult.version} as base`,
-      "info"
-    );
-    return calculateNextVersion(
-      manifestResult.version,
-      manifestResult.manifestType || "manifest",
-      name,
-      releaseType,
-      prereleaseIdentifier,
-      initialVersion
-    );
-  }
-  throwIfNoManifestsFound(packageDir);
-}
-function calculateNextVersion(version, manifestType, name, releaseType, prereleaseIdentifier, initialVersion) {
-  log(
-    `No tags found for ${name || "package"}, using ${manifestType} version: ${version} as base`,
-    "info"
-  );
-  if (STANDARD_BUMP_TYPES.includes(releaseType) && (semver3.prerelease(version) || prereleaseIdentifier)) {
-    log(
-      prereleaseIdentifier ? `Creating prerelease version with identifier '${prereleaseIdentifier}' using ${releaseType}` : `Cleaning prerelease identifier from ${version} for ${releaseType} bump`,
-      "debug"
-    );
-    return bumpVersion(version, releaseType, prereleaseIdentifier);
-  }
-  const result = bumpVersion(version, releaseType, prereleaseIdentifier);
-  return result || initialVersion;
-}
 
 // src/utils/packageMatching.ts
 import micromatch2 from "micromatch";
@@ -1770,14 +1764,14 @@ var PackageProcessor = class {
         try {
           let revisionRange;
           if (latestTag) {
-            try {
-              execSync4(`git rev-parse --verify "${latestTag}"`, {
-                cwd: pkgPath,
-                stdio: "ignore"
-              });
+            const verification = verifyTag(latestTag, pkgPath);
+            if (verification.exists && verification.reachable) {
               revisionRange = `${latestTag}..HEAD`;
-            } catch {
-              log(`Tag ${latestTag} doesn't exist, using all commits for changelog`, "debug");
+            } else {
+              log(
+                `Tag ${latestTag} is unreachable (${verification.error}), using all commits for changelog`,
+                "debug"
+              );
               revisionRange = "HEAD";
             }
           } else {
@@ -1966,7 +1960,7 @@ function createSyncedStrategy(config) {
         mainPackage
       } = config;
       const formattedPrefix = formatVersionPrefix(versionPrefix || "v");
-      const latestTag = await getLatestTag();
+      let latestTag = await getLatestTag();
       let mainPkgPath = packages.root;
       let mainPkgName;
       if (mainPackage) {
@@ -1989,6 +1983,21 @@ function createSyncedStrategy(config) {
           "warning"
         );
       }
+      if (mainPkgName) {
+        const packageSpecificTag = await getLatestTagForPackage(mainPkgName, formattedPrefix, {
+          tagTemplate,
+          packageSpecificTags: config.packageSpecificTags
+        });
+        if (packageSpecificTag) {
+          latestTag = packageSpecificTag;
+          log(`Using package-specific tag for ${mainPkgName}: ${latestTag}`, "debug");
+        } else {
+          log(
+            `No package-specific tag found for ${mainPkgName}, using global tag: ${latestTag}`,
+            "debug"
+          );
+        }
+      }
       const nextVersion = await calculateVersion(config, {
         latestTag,
         versionPrefix: formattedPrefix,
@@ -2131,7 +2140,7 @@ function createSingleStrategy(config) {
           let revisionRange;
           if (latestTag) {
             try {
-              execSync5(`git rev-parse --verify "${latestTag}"`, {
+              execSync4(`git rev-parse --verify "${latestTag}"`, {
                 cwd: pkgPath,
                 stdio: "ignore"
               });
@@ -2417,11 +2426,22 @@ async function run() {
     program.command("version", { isDefault: true }).description("Version a package or packages based on configuration").option(
       "-c, --config <path>",
       "Path to config file (defaults to version.config.json in current directory)"
-    ).option("-d, --dry-run", "Dry run (no changes made)", false).option("-b, --bump <type>", "Specify bump type (patch|minor|major)").option("-p, --prerelease [identifier]", "Create prerelease version").option("-s, --synced", "Use synchronized versioning across all packages").option("-j, --json", "Output results as JSON", false).option("-t, --target <packages>", "Comma-delimited list of package names to target").action(async (options) => {
+    ).option("-d, --dry-run", "Dry run (no changes made)", false).option("-b, --bump <type>", "Specify bump type (patch|minor|major)").option("-p, --prerelease [identifier]", "Create prerelease version").option("-s, --synced", "Use synchronized versioning across all packages").option("-j, --json", "Output results as JSON", false).option("-t, --target <packages>", "Comma-delimited list of package names to target").option("--project-dir <path>", "Project directory to run commands in", process.cwd()).action(async (options) => {
       if (options.json) {
         enableJsonOutput(options.dryRun);
       }
       try {
+        const originalCwd = process.cwd();
+        if (options.projectDir && options.projectDir !== originalCwd) {
+          try {
+            process.chdir(options.projectDir);
+            log(`Changed working directory to: ${options.projectDir}`, "debug");
+          } catch (error) {
+            throw new Error(
+              `Failed to change to directory "${options.projectDir}": ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+        }
         const config = await loadConfig(options.config);
         log(`Loaded configuration from ${options.config || "version.config.json"}`, "info");
         if (options.dryRun) config.dryRun = true;

package/docs/CI_CD_INTEGRATION.md

@@ -180,4 +180,5 @@ Each CI system might have slightly different syntax, so check your CI provider's
 2. **Use the `fetch-depth: 0`** option in GitHub Actions (or equivalent in other CIs) to ensure access to the full Git history
 3. **Store the JSON output** as a build artifact for debugging and auditing
 4. **Consider dry runs** in your preview/staging branches to validate version changes before they're applied
-5. **Be mindful of Git credentials** - ensure your CI has proper permissions for creating commits and tags 
+5. **Use `--project-dir`** when running from a different directory than your project root
+6. **Be mindful of Git credentials** - ensure your CI has proper permissions for creating commits and tags 

package/docs/changelogs.md

@@ -52,7 +52,14 @@ You can configure the preferred format in your `version.config.json`:
 For projects with existing history, you can regenerate a complete changelog from scratch using the CLI:
 
 ```bash
+# Generate changelog in current directory
 npx package-versioner changelog --regenerate
+
+# Generate changelog in a specific directory
+npx package-versioner changelog --regenerate --project-dir /path/to/project
+
+# Customize output path and format
+npx package-versioner changelog --regenerate --output CHANGELOG.md --format keep-a-changelog
 ```
 
 This will scan your entire git history and create a comprehensive changelog based on all version tags found in your repository.

package/docs/versioning.md

@@ -65,78 +65,6 @@ You define patterns in the `branchPattern` array in `version.config.json`. Each
 
 This allows you to enforce version bumps based on your branching workflow (e.g., all branches starting with `feature/` result in a minor bump).
 
-## Monorepo Versioning Modes
-
-While primarily used for single packages now, `package-versioner` retains options for monorepo workflows, controlled mainly by the `synced` flag in `version.config.json`.
-
-### Synced Mode (`synced: true`)
-
-This is the default if the `synced` flag is present and true.
-
--   **Behaviour:** The tool calculates **one** version bump based on the overall history (or branch pattern). This single new version is applied to **all** packages within the repository (or just the root `package.json` if not a structured monorepo). A single Git tag is created.
--   **Tag Behaviour:** 
-    - In **multi-package monorepos**: Creates global tags like `v1.2.3` regardless of `packageSpecificTags` setting
-    - In **single-package repositories**: Respects the `packageSpecificTags` setting - can create either `v1.2.3` or `package-name@v1.2.3`
--   **Use Case:** Suitable for monorepos where all packages are tightly coupled and released together with the same version number. Also the effective mode for single-package repositories.
-
-### Async Mode (`synced: false`)
-
-*(Note: This mode relies heavily on monorepo tooling and structure, like `pnpm workspaces` and correctly configured package dependencies.)*
-
--   **Behaviour (Default - No `-t` flag):** The tool analyzes commits to determine which specific packages within the monorepo have changed since the last relevant commit/tag.
-    -   It calculates an appropriate version bump **independently for each changed package** based on the commits affecting that package.
-    -   Only the `package.json` files of the changed packages are updated.
-    -   A **single commit** is created grouping all the version bumps, using the commit message template. **No Git tags are created** in this mode.
--   **Use Case:** Suitable for monorepos where packages are versioned independently, but a single commit represents the batch of updates for traceability.
-
--   **Behaviour (Targeted - With `-t` flag):** When using the `-t, --target <targets>` flag:
-    -   Only the specified packages (respecting the `skip` list) are considered for versioning.
-    -   It calculates an appropriate version bump **independently for each targeted package** based on its commit history.
-    -   The `package.json` file of each successfully updated targeted package is modified.
-    -   An **individual Git tag** (e.g., `packageName@1.2.3`) is created **for each successfully updated package** immediately after its version is bumped.
-    -   Finally, a **single commit** is created including all the updated `package.json` files, using a summary commit message (e.g., `chore(release): pkg-a, pkg-b 1.2.3 [skip-ci]`).
-    -   **Important:** Only package-specific tags are created. The global tag (e.g., `v1.2.3`) is **not** automatically generated in this mode. If your release process (like GitHub Releases) depends on a global tag, you'll need to create it manually in your CI/CD script *after* `package-versioner` completes.
--   **Use Case:** Releasing specific packages independently while still tagging each released package individually.
-
-## Prerelease Handling
-
-`package-versioner` provides flexible handling for prerelease versions, allowing both creation of prereleases and promotion to stable releases.
-
-### Creating Prereleases
-
-Use the `--prerelease` flag with an identifier to create a prerelease version:
-
-```bash
-# Create a beta prerelease
-npx package-versioner --bump minor --prerelease beta
-# Result: 1.0.0 -> 1.1.0-beta.0
-```
-
-You can also set a default prerelease identifier in your `version.config.json`:
-
-```json
-{
-  "prereleaseIdentifier": "beta"
-}
-```
-
-### Promoting Prereleases to Stable Releases
-
-When using standard bump types (`major`, `minor`, `patch`) with the `--bump` flag on a prerelease version, `package-versioner` will automatically clean the prerelease identifier:
-
-```bash
-# Starting from version 1.0.0-beta.1
-npx package-versioner --bump major
-# Result: 1.0.0-beta.1 -> 2.0.0 (not 2.0.0-beta.0)
-```
-
-This intuitive behaviour means you don't need to use an empty prerelease identifier (`--prerelease ""`) to promote a prerelease to a stable version. Simply specify the standard bump type and the tool will automatically produce a clean version number.
-
-This applies to all standard bump types:
-- `--bump major`: 1.0.0-beta.1 -> 2.0.0
-- `--bump minor`: 1.0.0-beta.1 -> 1.1.0 
-- `--bump patch`: 1.0.0-beta.1 -> 1.0.1
-
 ## Package Type Support
 
 `package-versioner` supports both JavaScript/TypeScript projects using `package.json` and Rust projects using `Cargo.toml`:
@@ -149,11 +77,6 @@ For JavaScript/TypeScript projects, the tool looks for and updates the `version`
 
 For Rust projects, the tool looks for and updates the `package.version` field in `Cargo.toml` files using the same versioning strategies.
 
-When no tags are found for a project, `package-versioner` will:
-1. Look for the `version` in `package.json` if it exists
-2. Look for the `package.version` in `Cargo.toml` if it exists
-3. Fall back to the configured `initialVersion` (default: "0.1.0")
-
 ### Mixed Projects with Both Manifests
 
 When both `package.json` and `Cargo.toml` exist in the same directory, `package-versioner` will:
@@ -164,7 +87,48 @@ When both `package.json` and `Cargo.toml` exist in the same directory, `package-
 
 This allows you to maintain consistent versioning across JavaScript and Rust components in the same package.
 
-This dual support makes `package-versioner` suitable for both JavaScript/TypeScript and Rust repositories, as well as monorepos or projects containing both types of packages.
+## Version Source Selection
+
+`package-versioner` uses a smart version source selection strategy to determine the base version for calculating the next version:
+
+1. First, it checks for Git tags:
+   - In normal mode: Uses the latest reachable tag, falling back to unreachable tags if needed
+   - In strict mode (`--strict-reachable`): Only uses reachable tags
+   
+2. Then, it checks manifest files (package.json, Cargo.toml):
+   - Reads version from package.json if it exists
+   - Falls back to Cargo.toml if package.json doesn't exist or has no version
+   
+3. Finally, it compares the versions:
+   - If both Git tag and manifest versions exist, it uses the newer version
+   - If the versions are equal, it prefers the Git tag for better history tracking
+   - If only one source has a version, it uses that
+   - If no version is found, it uses the default initial version (0.1.0)
+
+This strategy ensures that:
+- Version numbers never go backwards
+- Git history is respected when possible
+- Manifest files are considered as valid version sources
+- The tool always has a valid base version to work from
+
+For example:
+```
+Scenario 1:
+- Git tag: v1.0.0
+- package.json: 1.1.0
+Result: Uses 1.1.0 as base (package.json is newer)
+
+Scenario 2:
+- Git tag: v1.0.0
+- package.json: 1.0.0
+Result: Uses v1.0.0 as base (versions equal, prefer Git)
+
+Scenario 3:
+- Git tag: unreachable v2.0.0
+- package.json: 1.0.0
+Result: Uses 2.0.0 as base in normal mode (unreachable tag is newer)
+        Uses 1.0.0 as base in strict mode (unreachable tag ignored)
+```
 
 ## Package Targeting in Monorepos
 
@@ -430,3 +394,75 @@ For global commit messages, use templates without `${packageName}`:
   "commitMessage": "chore: release ${version}"
 }
 ```
+
+## Monorepo Versioning Modes
+
+While primarily used for single packages now, `package-versioner` retains options for monorepo workflows, controlled mainly by the `synced` flag in `version.config.json`.
+
+### Synced Mode (`synced: true`)
+
+This is the default if the `synced` flag is present and true.
+
+-   **Behaviour:** The tool calculates **one** version bump based on the overall history (or branch pattern). This single new version is applied to **all** packages within the repository (or just the root `package.json` if not a structured monorepo). A single Git tag is created.
+-   **Tag Behaviour:** 
+    - In **multi-package monorepos**: Creates global tags like `v1.2.3` regardless of `packageSpecificTags` setting
+    - In **single-package repositories**: Respects the `packageSpecificTags` setting - can create either `v1.2.3` or `package-name@v1.2.3`
+-   **Use Case:** Suitable for monorepos where all packages are tightly coupled and released together with the same version number. Also the effective mode for single-package repositories.
+
+### Async Mode (`synced: false`)
+
+*(Note: This mode relies heavily on monorepo tooling and structure, like `pnpm workspaces` and correctly configured package dependencies.)*
+
+-   **Behaviour (Default - No `-t` flag):** The tool analyzes commits to determine which specific packages within the monorepo have changed since the last relevant commit/tag.
+    -   It calculates an appropriate version bump **independently for each changed package** based on the commits affecting that package.
+    -   Only the `package.json` files of the changed packages are updated.
+    -   A **single commit** is created grouping all the version bumps, using the commit message template. **No Git tags are created** in this mode.
+-   **Use Case:** Suitable for monorepos where packages are versioned independently, but a single commit represents the batch of updates for traceability.
+
+-   **Behaviour (Targeted - With `-t` flag):** When using the `-t, --target <targets>` flag:
+    -   Only the specified packages (respecting the `skip` list) are considered for versioning.
+    -   It calculates an appropriate version bump **independently for each targeted package** based on its commit history.
+    -   The `package.json` file of each successfully updated targeted package is modified.
+    -   An **individual Git tag** (e.g., `packageName@1.2.3`) is created **for each successfully updated package** immediately after its version is bumped.
+    -   Finally, a **single commit** is created including all the updated `package.json` files, using a summary commit message (e.g., `chore(release): pkg-a, pkg-b 1.2.3 [skip-ci]`).
+    -   **Important:** Only package-specific tags are created. The global tag (e.g., `v1.2.3`) is **not** automatically generated in this mode. If your release process (like GitHub Releases) depends on a global tag, you'll need to create it manually in your CI/CD script *after* `package-versioner` completes.
+-   **Use Case:** Releasing specific packages independently while still tagging each released package individually.
+
+## Prerelease Handling
+
+`package-versioner` provides flexible handling for prerelease versions, allowing both creation of prereleases and promotion to stable releases.
+
+### Creating Prereleases
+
+Use the `--prerelease` flag with an identifier to create a prerelease version:
+
+```bash
+# Create a beta prerelease
+npx package-versioner --bump minor --prerelease beta
+# Result: 1.0.0 -> 1.1.0-beta.0
+```
+
+You can also set a default prerelease identifier in your `version.config.json`:
+
+```json
+{
+  "prereleaseIdentifier": "beta"
+}
+```
+
+### Promoting Prereleases to Stable Releases
+
+When using standard bump types (`major`, `minor`, `patch`) with the `--bump` flag on a prerelease version, `package-versioner` will automatically clean the prerelease identifier:
+
+```bash
+# Starting from version 1.0.0-beta.1
+npx package-versioner --bump major
+# Result: 1.0.0-beta.1 -> 2.0.0 (not 2.0.0-beta.0)
+```
+
+This intuitive behaviour means you don't need to use an empty prerelease identifier (`--prerelease ""`) to promote a prerelease to a stable version. Simply specify the standard bump type and the tool will automatically produce a clean version number.
+
+This applies to all standard bump types:
+- `--bump major`: 1.0.0-beta.1 -> 2.0.0
+- `--bump minor`: 1.0.0-beta.1 -> 1.1.0 
+- `--bump patch`: 1.0.0-beta.1 -> 1.0.1

package/package-versioner.schema.json

@@ -53,7 +53,7 @@
         "minLength": 1
       },
       "default": [],
-      "description": "Array of package names or patterns that determines which packages will be processed for versioning. When specified, only packages matching these patterns will be versioned. When empty or not specified, all workspace packages will be processed. Supports exact names (e.g., '@scope/package-a'), scope wildcards (e.g., '@scope/*'), and global wildcards (e.g., '*')"
+      "description": "Array of package names or patterns that determines which packages will be processed for versioning. When specified, only packages matching these patterns will be versioned. When empty or not specified, all workspace packages will be processed. Supports exact names (e.g., '@scope/package-a'), scope wildcards (e.g., '@scope/*'), path patterns (e.g., 'packages/**/*', 'examples/**'), and global wildcards (e.g., '*')."
     },
     "mainPackage": {
       "type": "string",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "package-versioner",
   "description": "A lightweight yet powerful CLI tool for automated semantic versioning based on Git history and conventional commits.",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",