@versu/core 0.4.0

package/dist/services/version-applier.js

@@ -0,0 +1,63 @@
+import { logger } from "../utils/logger.js";
+import { formatSemVer } from "../semver/index.js";
+export class VersionApplier {
+    versionManager;
+    options;
+    constructor(versionManager, options) {
+        this.versionManager = versionManager;
+        this.options = options;
+    }
+    async applyVersionChanges(processedModuleChanges) {
+        if (processedModuleChanges.length === 0) {
+            logger.info("✨ No version changes to apply");
+            return [];
+        }
+        logger.info("🔍 Filtering modules with declared versions...");
+        const modulesWithDeclaredVersions = processedModuleChanges.filter((change) => change.module.declaredVersion);
+        if (modulesWithDeclaredVersions.length === 0) {
+            logger.info("✨ No modules with declared versions to update");
+            return [];
+        }
+        this.logPlannedChanges(modulesWithDeclaredVersions);
+        if (this.options.dryRun) {
+            logger.info("🏃‍♂️ Dry run mode - version changes will not be written to files");
+        }
+        else {
+            await this.stageVersions(modulesWithDeclaredVersions);
+            await this.commitVersions();
+        }
+        // Create and return result objects
+        return processedModuleChanges.map((change) => ({
+            id: change.module.id,
+            name: change.module.name,
+            path: change.module.path,
+            type: change.module.type,
+            from: formatSemVer(change.fromVersion),
+            to: change.toVersion,
+            bumpType: change.bumpType,
+            declaredVersion: change.module.declaredVersion,
+        }));
+    }
+    logPlannedChanges(processedModuleChanges) {
+        logger.info(`📈 Planning to update ${processedModuleChanges.length} modules:`);
+        for (const change of processedModuleChanges) {
+            const from = formatSemVer(change.fromVersion);
+            const to = change.toVersion;
+            logger.info(`  ${change.module.id}: ${from} → ${to} (${change.bumpType}, ${change.reason})`);
+        }
+    }
+    async stageVersions(processedModuleChanges) {
+        logger.info("✍️ Staging new versions...");
+        for (const change of processedModuleChanges) {
+            // Use toVersion directly (now includes all transformations like Gradle snapshots)
+            this.versionManager.updateVersion(change.module.id, change.toVersion);
+            logger.info(`  Staged ${change.module.id} to ${change.toVersion}`);
+        }
+    }
+    async commitVersions() {
+        logger.info("💾 Committing version updates to files...");
+        const pendingUpdatesCount = this.versionManager.getPendingUpdatesCount();
+        await this.versionManager.commit();
+        logger.info(`✅ Committed ${pendingUpdatesCount} version updates`);
+    }
+}

package/dist/services/version-bumper.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Version Bumper Service for VERSU.
+ * Implements core version calculation logic: analyzes commits, cascades changes through
+ * dependencies, and applies versions with support for prereleases, metadata, and snapshots.
+ */
+import { Config } from "../config/index.js";
+import { ModuleRegistry } from "./module-registry.js";
+import { BumpType } from "../semver/index.js";
+import { SemVer } from "semver";
+import { AdapterMetadata } from "./adapter-identifier.js";
+import { Module } from "../adapters/project-information.js";
+import { Commit } from "conventional-commits-parser";
+/**
+ * Configuration options for the version bumper service.
+ */
+export type VersionBumperOptions = {
+    /** Whether to generate prerelease versions (e.g., 1.0.0-alpha.1). */
+    prereleaseMode: boolean;
+    /** Whether to bump versions of unchanged modules in prerelease mode. */
+    bumpUnchanged: boolean;
+    /** Whether to add build metadata (commit SHA) to versions. */
+    addBuildMetadata: boolean;
+    /** Whether to append -SNAPSHOT suffix for Gradle projects. */
+    appendSnapshot: boolean;
+    /** Adapter metadata providing project-specific capabilities. */
+    adapter: AdapterMetadata;
+    /** Whether to include timestamps in prerelease identifiers. */
+    timestampVersions: boolean;
+    /** Base prerelease identifier (e.g., 'alpha', 'beta', 'rc'). */
+    prereleaseId: string;
+    /** Absolute path to the repository root directory. */
+    repoRoot: string;
+    /** Project configuration including dependency bump rules. */
+    config: Config;
+};
+/**
+ * Final processed module version change result.
+ * Represents a completed version calculation ready for application.
+ */
+export type ProcessedModuleChange = {
+    /** The module with calculated version change. */
+    readonly module: Module;
+    /** Original semantic version before changes. */
+    readonly fromVersion: SemVer;
+    /** New calculated version string (e.g., '1.1.0', '1.1.0-alpha.1', '1.1.0-SNAPSHOT'). */
+    readonly toVersion: string;
+    /** Final bump type applied ('major', 'minor', 'patch', or 'none'). */
+    readonly bumpType: BumpType;
+    /** Reason for version change. */
+    readonly reason: ChangeReason;
+};
+/**
+ * Reason why a module's version is being changed.
+ */
+export type ChangeReason = "commits" | "dependency" | "cascade" | "prerelease-unchanged" | "build-metadata" | "gradle-snapshot";
+/**
+ * Service for calculating version bumps across modules.
+ * Handles commit analysis, dependency cascade effects, and various versioning strategies
+ * (regular, prerelease, snapshot).
+ */
+export declare class VersionBumper {
+    private readonly moduleRegistry;
+    private readonly options;
+    /**
+     * Creates a new VersionBumper instance.
+     * @param moduleRegistry - Registry containing all modules and their interdependencies
+     * @param options - Configuration options controlling version bump behavior
+     */
+    constructor(moduleRegistry: ModuleRegistry, options: VersionBumperOptions);
+    /**
+     * Calculates version bumps for all modules based on their commits.
+     * Orchestrates a three-phase process: initial bumps (commit analysis), cascade effects (dependency propagation),
+     * and version application (applying strategies like prerelease, timestamps, build metadata).
+     * @param moduleCommits - Map of module IDs to their commits since last version
+     * @returns Promise resolving to array of processed module changes (only modules that need updates)
+     * @throws {Error} If git operations fail
+     */
+    calculateVersionBumps(moduleCommits: Map<string, {
+        commits: Commit[];
+        lastTag: string | null;
+    }>): Promise<ProcessedModuleChange[]>;
+    /**
+     * Calculates initial version bump types for all modules based on commits.
+     *
+     * This is Phase 1 of the version calculation process. It analyzes commits for each
+     * module to determine the required version bump type using Conventional Commits
+     * specification.
+     *
+     * The method creates a `ProcessingModuleChange` for **every** module in the registry,
+     * not just those with commits. The `needsProcessing` flag determines which modules
+     * will ultimately be updated.
+     *
+     * **Processing Decision Logic**:
+     * - Module has commits requiring bump: `needsProcessing = true, reason = 'commits'`
+     * - Prerelease mode with bumpUnchanged: `needsProcessing = true, reason = 'prerelease-unchanged'`
+     * - Build metadata enabled: `needsProcessing = true, reason = 'build-metadata'`
+     * - Otherwise: `needsProcessing = false, reason = 'unchanged'`
+     *
+     * @param moduleCommits - Map of module IDs to their commits since last version.
+     *
+     * @returns Array of processing module changes for all modules in the registry
+     */
+    private calculateInitialBumps;
+    /**
+     * Calculates cascade effects when modules change.
+     *
+     * This is Phase 2 of the version calculation process. It propagates version changes
+     * through the module dependency graph, ensuring that when a module changes, all
+     * modules that depend on it are also bumped appropriately.
+     *
+     * **Algorithm**: Uses a breadth-first traversal of the dependency graph:
+     * 1. Start with all modules marked for processing (needsProcessing = true)
+     * 2. For each module being processed, find all modules that depend on it
+     * 3. Calculate required bump for dependents using dependency bump rules
+     * 4. If dependent needs a higher bump, update it and add to processing queue
+     * 5. Continue until no more cascades are needed
+     *
+     * **Complexity**: O(V + E) where V = number of modules, E = number of dependencies
+     *
+     * **In-Place Modification**: This method modifies the input array in place for
+     * efficiency. The same array reference is returned with cascade effects applied.
+     *
+     * @param allModuleChanges - Array of all module changes (will be modified in place).
+     *                          Should include all modules from calculateInitialBumps().
+     *
+     * @returns The same array with cascade effects applied
+     */
+    private calculateCascadeEffects;
+    /**
+     * Applies version calculations and transformations to all modules.
+     *
+     * This is Phase 3 (final) of the version calculation process. It takes modules
+     * with calculated bump types and applies version transformations including:
+     * - Semantic version bumping (major, minor, patch)
+     * - Prerelease version generation
+     * - Build metadata appending
+     * - Snapshot suffix appending
+     *
+     * **Version Application Scenarios**:
+     * 1. **Commits + Regular Mode**: Bump semantic version normally
+     * 2. **Commits + Prerelease Mode**: Bump to prerelease version
+     * 3. **No Commits + Prerelease + bumpUnchanged**: Force prerelease bump
+     * 4. **Build Metadata Mode**: Append git SHA as metadata
+     * 5. **Snapshot Mode**: Append -SNAPSHOT suffix
+     *
+     * @param processingModuleChanges - All module changes with calculated bump types
+     *                                 from cascade effects phase.
+     *
+     * @param effectivePrereleaseId - Prerelease identifier to use (may include timestamp).
+     *                               Example: 'alpha', 'alpha.20251021143022'
+     *
+     * @param shortSha - Optional git commit short SHA for build metadata.
+     *                  Example: 'a1b2c3d'
+     *
+     * @returns Array of processed module changes ready for application (only modules with needsProcessing = true)
+     */
+    private applyVersionCalculations;
+}
+//# sourceMappingURL=version-bumper.d.ts.map

package/dist/services/version-bumper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-bumper.d.ts","sourceRoot":"","sources":["../../src/services/version-bumper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,MAAM,EAAyB,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAOL,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,qEAAqE;IACrE,cAAc,EAAE,OAAO,CAAC;IACxB,wEAAwE;IACxE,aAAa,EAAE,OAAO,CAAC;IACvB,8DAA8D;IAC9D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8DAA8D;IAC9D,cAAc,EAAE,OAAO,CAAC;IACxB,gEAAgE;IAChE,OAAO,EAAE,eAAe,CAAC;IACzB,+DAA+D;IAC/D,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAsBF;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,YAAY,GACZ,SAAS,GACT,sBAAsB,GACtB,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB;;;;GAIG;AACH,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B;;;;OAIG;gBAEgB,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,oBAAoB;IAGhD;;;;;;;OAOG;IACG,qBAAqB,CACzB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,GACxE,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAuCnC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,qBAAqB;IA6C7B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,uBAAuB;IAgG/B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,wBAAwB;CAgFjC"}

package/dist/services/version-bumper.js

@@ -0,0 +1,291 @@
+/**
+ * Version Bumper Service for VERSU.
+ * Implements core version calculation logic: analyzes commits, cascades changes through
+ * dependencies, and applies versions with support for prereleases, metadata, and snapshots.
+ */
+import { logger } from "../utils/logger.js";
+import { getDependencyBumpType } from "../config/index.js";
+import { calculateBumpFromCommits } from "../utils/commits.js";
+import { bumpSemVer, bumpToPrerelease, formatSemVer, addBuildMetadata, generateTimestampPrereleaseId, maxBumpType, } from "../semver/index.js";
+import { getCurrentCommitShortSha } from "../git/index.js";
+import { applySnapshotSuffix } from "../utils/versioning.js";
+/**
+ * Service for calculating version bumps across modules.
+ * Handles commit analysis, dependency cascade effects, and various versioning strategies
+ * (regular, prerelease, snapshot).
+ */
+export class VersionBumper {
+    moduleRegistry;
+    options;
+    /**
+     * Creates a new VersionBumper instance.
+     * @param moduleRegistry - Registry containing all modules and their interdependencies
+     * @param options - Configuration options controlling version bump behavior
+     */
+    constructor(moduleRegistry, options) {
+        this.moduleRegistry = moduleRegistry;
+        this.options = options;
+    }
+    /**
+     * Calculates version bumps for all modules based on their commits.
+     * Orchestrates a three-phase process: initial bumps (commit analysis), cascade effects (dependency propagation),
+     * and version application (applying strategies like prerelease, timestamps, build metadata).
+     * @param moduleCommits - Map of module IDs to their commits since last version
+     * @returns Promise resolving to array of processed module changes (only modules that need updates)
+     * @throws {Error} If git operations fail
+     */
+    async calculateVersionBumps(moduleCommits) {
+        logger.info("🔢 Calculating version bumps from commits...");
+        // Generate timestamp-based prerelease ID if timestamp versions are enabled
+        let effectivePrereleaseId = this.options.prereleaseId;
+        if (this.options.timestampVersions && this.options.prereleaseMode) {
+            effectivePrereleaseId = generateTimestampPrereleaseId(this.options.prereleaseId);
+            logger.info(`🕐 Generated timestamp prerelease ID: ${effectivePrereleaseId}`);
+        }
+        // Get current commit short SHA if build metadata is enabled
+        let shortSha;
+        if (this.options.addBuildMetadata) {
+            shortSha = await getCurrentCommitShortSha({ cwd: this.options.repoRoot });
+            logger.info(`📋 Build metadata will include short SHA: ${shortSha}`);
+        }
+        // Step 1: Calculate initial bump types for all modules
+        const processingModuleChanges = this.calculateInitialBumps(moduleCommits);
+        // Step 2: Calculate cascade effects
+        logger.info("🌊 Calculating cascade effects...");
+        const cascadedChanges = this.calculateCascadeEffects(processingModuleChanges);
+        // Step 3: Apply version calculations and transformations
+        logger.info("🔢 Calculating actual versions...");
+        return this.applyVersionCalculations(cascadedChanges, effectivePrereleaseId, shortSha);
+    }
+    /**
+     * Calculates initial version bump types for all modules based on commits.
+     *
+     * This is Phase 1 of the version calculation process. It analyzes commits for each
+     * module to determine the required version bump type using Conventional Commits
+     * specification.
+     *
+     * The method creates a `ProcessingModuleChange` for **every** module in the registry,
+     * not just those with commits. The `needsProcessing` flag determines which modules
+     * will ultimately be updated.
+     *
+     * **Processing Decision Logic**:
+     * - Module has commits requiring bump: `needsProcessing = true, reason = 'commits'`
+     * - Prerelease mode with bumpUnchanged: `needsProcessing = true, reason = 'prerelease-unchanged'`
+     * - Build metadata enabled: `needsProcessing = true, reason = 'build-metadata'`
+     * - Otherwise: `needsProcessing = false, reason = 'unchanged'`
+     *
+     * @param moduleCommits - Map of module IDs to their commits since last version.
+     *
+     * @returns Array of processing module changes for all modules in the registry
+     */
+    calculateInitialBumps(moduleCommits) {
+        const processingModuleChanges = [];
+        // Iterate through ALL modules in the registry
+        for (const [projectId, projectInfo] of this.moduleRegistry.getModules()) {
+            const commits = moduleCommits.get(projectId)?.commits || [];
+            // Determine bump type from commits only
+            // Uses Conventional Commits spec to analyze commit types
+            const bumpType = calculateBumpFromCommits(commits, this.options.config);
+            // Determine processing requirements and reason
+            let reason = "unchanged";
+            let needsProcessing = false;
+            if (bumpType !== "none") {
+                // Module has commits that require version changes
+                needsProcessing = true;
+                reason = "commits";
+            }
+            else if (this.options.prereleaseMode && this.options.bumpUnchanged) {
+                // Prerelease mode with bumpUnchanged - include modules with no changes
+                needsProcessing = true;
+                reason = "prerelease-unchanged";
+            }
+            else if (this.options.addBuildMetadata) {
+                // Build metadata mode - all modules need updates for metadata
+                needsProcessing = true;
+                reason = "build-metadata";
+            }
+            // Create module change for ALL modules - processing flag determines behavior
+            processingModuleChanges.push({
+                module: projectInfo,
+                fromVersion: projectInfo.version,
+                toVersion: "", // Will be calculated later
+                bumpType: bumpType,
+                reason: reason,
+                needsProcessing: needsProcessing,
+            });
+        }
+        return processingModuleChanges;
+    }
+    /**
+     * Calculates cascade effects when modules change.
+     *
+     * This is Phase 2 of the version calculation process. It propagates version changes
+     * through the module dependency graph, ensuring that when a module changes, all
+     * modules that depend on it are also bumped appropriately.
+     *
+     * **Algorithm**: Uses a breadth-first traversal of the dependency graph:
+     * 1. Start with all modules marked for processing (needsProcessing = true)
+     * 2. For each module being processed, find all modules that depend on it
+     * 3. Calculate required bump for dependents using dependency bump rules
+     * 4. If dependent needs a higher bump, update it and add to processing queue
+     * 5. Continue until no more cascades are needed
+     *
+     * **Complexity**: O(V + E) where V = number of modules, E = number of dependencies
+     *
+     * **In-Place Modification**: This method modifies the input array in place for
+     * efficiency. The same array reference is returned with cascade effects applied.
+     *
+     * @param allModuleChanges - Array of all module changes (will be modified in place).
+     *                          Should include all modules from calculateInitialBumps().
+     *
+     * @returns The same array with cascade effects applied
+     */
+    calculateCascadeEffects(allModuleChanges) {
+        const processed = new Set();
+        const moduleMap = new Map();
+        // Create module map for O(1) lookups
+        for (const change of allModuleChanges) {
+            moduleMap.set(change.module.id, change);
+        }
+        // Start with ALL modules - treat them completely equally
+        const queue = [...allModuleChanges];
+        while (queue.length > 0) {
+            const currentChange = queue.shift();
+            // No processing needed, mark as processed
+            if (!currentChange.needsProcessing || currentChange.bumpType === "none") {
+                logger.debug(`🔄 Skipping module ${currentChange.module.id} - no processing needed`);
+                processed.add(currentChange.module.id);
+                continue;
+            }
+            // Skip if already processed
+            if (processed.has(currentChange.module.id)) {
+                logger.debug(`🔄 Skipping module ${currentChange.module.id} - already processed`);
+                continue;
+            }
+            // Mark as processed to avoid duplicate work
+            processed.add(currentChange.module.id);
+            const currentModuleInfo = this.moduleRegistry.getModule(currentChange.module.id);
+            // Iterate through all modules that depend on the current module
+            for (const dependentName of currentModuleInfo.affectedModules) {
+                logger.debug(`➡️ Processing dependent module ${dependentName} affected by ${currentChange.module.id} with bump ${currentChange.bumpType}`);
+                // Get the dependent module using O(1) lookup
+                const existingChange = moduleMap.get(dependentName);
+                if (!existingChange) {
+                    logger.debug(`⚠️ Dependent module ${dependentName} not found in module changes list`);
+                    continue; // Module not found in our module list
+                }
+                // Calculate the bump needed for the dependent
+                // Uses configuration rules to determine how changes propagate
+                const requiredBump = getDependencyBumpType(currentChange.bumpType, this.options.config);
+                if (requiredBump === "none") {
+                    logger.debug(`➡️ No cascade bump needed for module ${dependentName} from ${currentChange.module.id}`);
+                    continue; // No cascade needed
+                }
+                // Update the existing change with cascade information
+                // Take the maximum bump type if multiple dependencies affect this module
+                const mergedBump = maxBumpType([existingChange.bumpType, requiredBump]);
+                if (mergedBump !== existingChange.bumpType) {
+                    logger.debug(`🔄 Cascading bump for module ${dependentName} from ${existingChange.bumpType} to ${mergedBump} due to ${currentChange.module.id}`);
+                    // Update the module change in place
+                    existingChange.bumpType = mergedBump;
+                    existingChange.reason = "cascade";
+                    existingChange.needsProcessing = true;
+                    // Add to queue for further processing (transitive cascades)
+                    processed.delete(dependentName); // Allow re-processing
+                    queue.push(existingChange);
+                }
+                else {
+                    logger.debug(`🔄 No changes needed for module ${dependentName} - already at ${existingChange.bumpType}`);
+                }
+            }
+        }
+        // Return the modified array (same reference, but with cascade effects applied)
+        return allModuleChanges;
+    }
+    /**
+     * Applies version calculations and transformations to all modules.
+     *
+     * This is Phase 3 (final) of the version calculation process. It takes modules
+     * with calculated bump types and applies version transformations including:
+     * - Semantic version bumping (major, minor, patch)
+     * - Prerelease version generation
+     * - Build metadata appending
+     * - Snapshot suffix appending
+     *
+     * **Version Application Scenarios**:
+     * 1. **Commits + Regular Mode**: Bump semantic version normally
+     * 2. **Commits + Prerelease Mode**: Bump to prerelease version
+     * 3. **No Commits + Prerelease + bumpUnchanged**: Force prerelease bump
+     * 4. **Build Metadata Mode**: Append git SHA as metadata
+     * 5. **Snapshot Mode**: Append -SNAPSHOT suffix
+     *
+     * @param processingModuleChanges - All module changes with calculated bump types
+     *                                 from cascade effects phase.
+     *
+     * @param effectivePrereleaseId - Prerelease identifier to use (may include timestamp).
+     *                               Example: 'alpha', 'alpha.20251021143022'
+     *
+     * @param shortSha - Optional git commit short SHA for build metadata.
+     *                  Example: 'a1b2c3d'
+     *
+     * @returns Array of processed module changes ready for application (only modules with needsProcessing = true)
+     */
+    applyVersionCalculations(processingModuleChanges, effectivePrereleaseId, shortSha) {
+        const processedModuleChanges = [];
+        for (const change of processingModuleChanges) {
+            let newVersion = change.fromVersion;
+            // Only apply version changes if module needs processing
+            if (change.needsProcessing) {
+                // Apply version bumps based on module state
+                if (change.bumpType !== "none" && this.options.prereleaseMode) {
+                    // Scenario 1: Commits with changes in prerelease mode
+                    // Bump semantic version AND add prerelease identifier
+                    newVersion = bumpToPrerelease(change.fromVersion, change.bumpType, effectivePrereleaseId);
+                }
+                else if (change.bumpType !== "none" && !this.options.prereleaseMode) {
+                    // Scenario 2: Commits with changes in normal mode
+                    // Standard semantic version bump (major.minor.patch)
+                    newVersion = bumpSemVer(change.fromVersion, change.bumpType);
+                }
+                else if (change.reason === "prerelease-unchanged") {
+                    // Scenario 3: No changes but force prerelease bump (bumpUnchanged enabled)
+                    // Keep semantic version, just add prerelease identifier
+                    newVersion = bumpToPrerelease(change.fromVersion, "none", effectivePrereleaseId);
+                }
+                // Scenario 4: reason === 'build-metadata' or 'unchanged' - no version bump, keep fromVersion
+                // Add build metadata if enabled (applies to all scenarios)
+                // Build metadata doesn't affect version precedence per semver spec
+                if (this.options.addBuildMetadata && shortSha) {
+                    newVersion = addBuildMetadata(newVersion, shortSha);
+                }
+            }
+            // Convert to string version
+            change.toVersion = formatSemVer(newVersion);
+            // Apply append snapshot suffix if enabled (to all modules in append mode)
+            if (this.options.appendSnapshot &&
+                this.options.adapter.capabilities.supportsSnapshots) {
+                const originalVersion = change.toVersion;
+                change.toVersion = applySnapshotSuffix(change.toVersion);
+                // If snapshot suffix was actually added and module wasn't already being processed, mark it for processing
+                if (!change.needsProcessing && change.toVersion !== originalVersion) {
+                    change.needsProcessing = true;
+                    change.reason = "gradle-snapshot";
+                }
+            }
+            // Add to update collection only if module needs processing
+            if (change.needsProcessing) {
+                // Convert to ProcessedModuleChange since we know needsProcessing is true
+                const processedChange = {
+                    module: change.module,
+                    fromVersion: change.fromVersion,
+                    toVersion: change.toVersion,
+                    bumpType: change.bumpType,
+                    reason: change.reason, // Safe cast since needsProcessing is true
+                };
+                processedModuleChanges.push(processedChange);
+            }
+        }
+        logger.info(`📈 Calculated versions for ${processedModuleChanges.length} modules requiring updates`);
+        return processedModuleChanges;
+    }
+}

package/dist/services/version-manager.d.ts

@@ -0,0 +1,68 @@
+import { SemVer } from "semver";
+import { ModuleRegistry } from "./module-registry.js";
+import { VersionUpdateStrategy } from "./version-update-strategy.js";
+/**
+ * Manages version updates for modules with staged commits and batch persistence.
+ *
+ * @remarks
+ * Implements a two-phase update strategy:
+ * 1. Stage updates in memory via `updateVersion()`
+ * 2. Persist all updates via `commit()`
+ *
+ * Uses {@link VersionUpdateStrategy} for build system-specific operations.
+ * Validates modules against {@link ModuleRegistry}.
+ */
+export declare class VersionManager {
+    private readonly moduleRegistry;
+    private readonly strategy;
+    /** Pending version updates awaiting commit (module ID → version string). */
+    private readonly pendingUpdates;
+    /**
+     * Creates a new VersionManager.
+     *
+     * @param moduleRegistry - Module registry for validation
+     * @param strategy - Build system-specific strategy for writing updates
+     */
+    constructor(moduleRegistry: ModuleRegistry, strategy: VersionUpdateStrategy);
+    /**
+     * Stages a version update for a module without persisting to files.
+     *
+     * @param moduleId - Module identifier (e.g., `':'`, `':core'`)
+     * @param newVersion - New version as SemVer object or string
+     * @throws {Error} If module ID doesn't exist in registry
+     */
+    updateVersion(moduleId: string, newVersion: SemVer | string): void;
+    /**
+     * Commits all pending version updates to build files in a single batch operation.
+     *
+     * @returns Promise that resolves when all updates are written
+     * @throws {Error} If file operations fail (specific errors depend on strategy)
+     */
+    commit(): Promise<void>;
+    /**
+     * Returns a copy of all pending updates that haven't been committed.
+     *
+     * @returns Map of module ID to version string
+     */
+    getPendingUpdates(): Map<string, string>;
+    /**
+     * Checks whether there are any pending updates awaiting commit.
+     *
+     * @returns `true` if updates are staged, `false` otherwise
+     */
+    hasPendingUpdates(): boolean;
+    /**
+     * Clears all pending updates without committing them.
+     *
+     * @remarks
+     * Use with caution - this operation cannot be undone.
+     */
+    clearPendingUpdates(): void;
+    /**
+     * Gets the number of pending updates in the queue.
+     *
+     * @returns The count of pending updates that have not been processed yet.
+     */
+    getPendingUpdatesCount(): number;
+}
+//# sourceMappingURL=version-manager.d.ts.map

package/dist/services/version-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-manager.d.ts","sourceRoot":"","sources":["../../src/services/version-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IAWvB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAX3B,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAE5D;;;;;OAKG;gBAEgB,cAAc,EAAE,cAAc,EAC9B,QAAQ,EAAE,qBAAqB;IAGlD;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAclE;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAa7B;;;;OAIG;IACH,iBAAiB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIxC;;;;OAIG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;;;;OAKG;IACH,mBAAmB,IAAI,IAAI;IAI3B;;;;OAIG;IACH,sBAAsB,IAAI,MAAM;CAGjC"}