semver-ratchet 1.0.0

package/src/cli.js

@@ -0,0 +1,431 @@
+/**
+ * Command-line interface for semver-ratchet.
+ */
+
+import {
+  getVersion,
+  getCurrentBranch,
+  calculateCrc32Unsigned,
+  determineVersionBump,
+  getCompatibleVersions,
+  verifyGitHistory,
+  createGitTag,
+  pushGitTag,
+  isMainBranch,
+  parseSemver,
+  getGitAdapter,
+} from './version.js';
+
+/**
+ * Display the current version.
+ * @param {Object} _args - Command line arguments
+ */
+function cmdVersion(_args) {
+  const version = getVersion(
+    _args.defaultBump || 'patch',
+    !_args.noVerify,
+  );
+  console.log(version);
+  process.exit(0);
+}
+
+/**
+ * Display the current branch name.
+ * @param {Object} _args - Command line arguments
+ */
+function cmdBranch(_args) {
+  const branch = getCurrentBranch();
+  console.log(branch);
+  process.exit(0);
+}
+
+/**
+ * Calculate CRC32 of a string (useful for branch name hashing).
+ * @param {Object} _args - Command line arguments
+ */
+function cmdCrc32(_args) {
+  const value = calculateCrc32Unsigned(_args.string);
+  console.log(value);
+  process.exit(0);
+}
+
+/**
+ * Validate a commit message for SemVer bump.
+ * @param {Object} _args - Command line arguments
+ */
+function cmdValidate(_args) {
+  const message = _args.message;
+  const messages = [message];
+  const bumpType = determineVersionBump(messages, _args.defaultBump || 'patch');
+
+  // Check for valid tags
+  if (message.toUpperCase().includes('[MAJOR]')) {
+    console.log(`Valid: ${bumpType.toUpperCase()} bump`);
+    console.log('  Tag: [MAJOR]');
+    process.exit(0);
+  } else if (message.toUpperCase().includes('[MINOR]')) {
+    console.log(`Valid: ${bumpType.toUpperCase()} bump`);
+    console.log('  Tag: [MINOR]');
+    process.exit(0);
+  } else if (message.toUpperCase().includes('[PATCH]')) {
+    console.log(`Valid: ${bumpType.toUpperCase()} bump`);
+    console.log('  Tag: [PATCH]');
+    process.exit(0);
+  } else {
+    console.log(`Valid: ${bumpType.toUpperCase()} bump (default: ${_args.defaultBump || 'patch'})`);
+    console.log(`  Tag: [${(_args.defaultBump || 'patch').toUpperCase()}] (implicit)`);
+    process.exit(0);
+  }
+}
+
+/**
+ * Compare two SemVer versions.
+ * @param {string} v1 - First version
+ * @param {string} v2 - Second version
+ * @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+function compareSemver(v1, v2) {
+  const { major: m1, minor: n1, patch: p1 } = parseSemver(v1);
+  const { major: m2, minor: n2, patch: p2 } = parseSemver(v2);
+
+  if (m1 !== m2) return m1 < m2 ? -1 : 1;
+  if (n1 !== n2) return n1 < n2 ? -1 : 1;
+  if (p1 !== p2) return p1 < p2 ? -1 : 1;
+  return 0;
+}
+
+/**
+ * Check if version is monotonic (increasing).
+ * @param {Object} _args - Command line arguments
+ */
+function cmdCheckMonotonic(_args) {
+  try {
+    const currentVersion = getVersion(
+      _args.defaultBump || 'patch',
+      !_args.noVerify,
+    );
+
+    // For main branch, compare with latest tag
+    if (isMainBranch()) {
+      try {
+        const adapter = getGitAdapter();
+        const latestTag = adapter.getLatestTag();
+
+        if (latestTag) {
+          const comparison = compareSemver(currentVersion, latestTag);
+
+          if (comparison > 0) {
+            console.log(`Monotonic: ${latestTag} -> ${currentVersion}`);
+            process.exit(0);
+          } else {
+            console.log(`ERROR: Version decreased or stayed same: ${latestTag} -> ${currentVersion}`);
+            process.exit(1);
+          }
+        } else {
+          // No tags yet, assume monotonic
+          console.log(`Monotonic: No previous tags, starting at ${currentVersion}`);
+          process.exit(0);
+        }
+      } catch {
+        // No tags yet, assume monotonic
+        console.log(`Monotonic: No previous tags, starting at ${currentVersion}`);
+        process.exit(0);
+      }
+    } else {
+      // Feature branches are always monotonic within their branch
+      console.log(`Monotonic: Feature branch version ${currentVersion}`);
+      process.exit(0);
+    }
+  } catch (error) {
+    console.log(`ERROR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Display versioning information.
+ * @param {Object} _args - Command line arguments
+ */
+function cmdInfo(_args) {
+  const branch = getCurrentBranch();
+  const version = getVersion(
+    _args.defaultBump || 'patch',
+    !_args.noVerify,
+  );
+  const branchType = isMainBranch() ? 'main' : 'feature';
+
+  console.log(`Branch: ${branch}`);
+  console.log(`Type: ${branchType}`);
+  console.log(`Version: ${version}`);
+  console.log(`Default bump: ${_args.defaultBump || 'patch'}`);
+
+  if (!isMainBranch()) {
+    const crc32 = calculateCrc32Unsigned(branch);
+    console.log(`Branch CRC32: ${crc32}`);
+  }
+
+  // Show compatible versions for main branch
+  if (isMainBranch()) {
+    try {
+      parseSemver(version);
+      const compatible = getCompatibleVersions(version);
+      console.log(`Compatible versions: ${compatible.join(', ')}`);
+    } catch {
+      // Not a valid semver, skip
+    }
+  }
+
+  process.exit(0);
+}
+
+/**
+ * Generate compatible versions in CSV format.
+ * @param {Object} _args - Command line arguments
+ */
+function cmdVersions(_args) {
+  try {
+    const version = getVersion(
+      _args.defaultBump || 'patch',
+      !_args.noVerify,
+    );
+
+    // Output as CSV
+    console.log('version,type,description');
+
+    const parts = version.split('.');
+    const major = parts[0];
+    const minor = parts[1];
+
+    console.log(`${version},full,Exact version ${version}`);
+    console.log(`${major}.${minor},minor,Compatible with ${major}.${minor}.x`);
+    console.log(`${major},major,Compatible with ${major}.x.x`);
+
+    process.exit(0);
+  } catch (error) {
+    console.log(`ERROR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Verify git history is sufficient for version calculation.
+ * @param {Object} _args - Command line arguments
+ */
+function cmdVerify(_args) {
+  try {
+    const depth = parseInt(_args.depth, 10) || 50;
+    verifyGitHistory(depth);
+    console.log('OK: Sufficient git history available');
+    process.exit(0);
+  } catch (error) {
+    console.log(`ERROR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Create and optionally push a Git tag for the current version.
+ * @param {Object} _args - Command line arguments
+ */
+function cmdTag(_args) {
+  if (!isMainBranch()) {
+    console.log('ERROR: Git tags can only be created on main branch');
+    process.exit(1);
+  }
+
+  try {
+    // Create tag (version is calculated internally)
+    createGitTag(_args.defaultBump || 'patch', _args.force);
+
+    // Push tag if requested
+    if (_args.push) {
+      pushGitTag(_args.defaultBump || 'patch', _args.remote || 'origin');
+    }
+
+    process.exit(0);
+  } catch (error) {
+    console.log(`ERROR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Parse command line arguments.
+ * @param {string[]} argv - Command line arguments
+ * @returns {Object} Parsed arguments
+ */
+function parseArgs(argv) {
+  const args = {
+    command: null,
+    defaultBump: 'patch',
+    noVerify: false,
+  };
+
+  const commands = ['version', 'branch', 'crc32', 'validate', 'check-monotonic', 'info', 'versions', 'verify', 'tag'];
+
+  let i = 2; // Skip node and script name
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    // Check for commands
+    if (commands.includes(arg)) {
+      args.command = arg;
+      i++;
+      continue;
+    }
+
+    // Check for flags
+    if (arg === '--default-bump') {
+      args.defaultBump = argv[++i];
+      i++;
+      continue;
+    }
+
+    if (arg === '--no-verify') {
+      args.noVerify = true;
+      i++;
+      continue;
+    }
+
+    if (arg === '--force') {
+      args.force = true;
+      i++;
+      continue;
+    }
+
+    if (arg === '--push') {
+      args.push = true;
+      i++;
+      continue;
+    }
+
+    if (arg === '--remote') {
+      args.remote = argv[++i];
+      i++;
+      continue;
+    }
+
+    if (arg === '--depth') {
+      args.depth = argv[++i];
+      i++;
+      continue;
+    }
+
+    // Positional arguments
+    if (args.command === 'crc32' && !args.string && !arg.startsWith('--')) {
+      args.string = arg;
+      i++;
+      continue;
+    }
+
+    if (args.command === 'validate' && !args.message && !arg.startsWith('--')) {
+      args.message = arg;
+      i++;
+      continue;
+    }
+
+    i++;
+  }
+
+  return args;
+}
+
+/**
+ * Print usage information.
+ */
+function printUsage() {
+  console.log(`
+Usage: semver-ratchet [options] <command>
+
+Forward-only versioning for Trunk-Based Development
+
+Commands:
+  version          Get current version
+  branch           Get current branch name
+  crc32 <string>   Calculate CRC32 of a string
+  validate <msg>   Validate commit message for SemVer bump
+  check-monotonic  Check version monotonicity
+  info             Display versioning information
+  versions         Generate compatible versions in CSV format
+  verify           Verify git history is sufficient
+  tag              Create and push a Git tag for the current version
+
+Global Options:
+  --default-bump <type>  Default version bump (major|minor|patch, default: patch)
+  --no-verify            Skip git history verification
+
+Tag Command Options:
+  --force                Overwrite existing tag if it exists
+  --push                 Push tag to remote after creating
+  --remote <name>        Remote name to push to (default: origin)
+
+Verify Command Options:
+  --depth <n>            Minimum required commit depth (default: 50)
+
+Examples:
+  semver-ratchet version
+  semver-ratchet version --default-bump minor
+  semver-ratchet validate "feat: add login [MINOR]"
+  semver-ratchet tag --push
+  semver-ratchet crc32 feature/my-branch
+`);
+}
+
+/**
+ * Main entry point for CLI.
+ */
+export function main() {
+  const args = parseArgs(process.argv);
+
+  if (!args.command) {
+    printUsage();
+    process.exit(1);
+  }
+
+  switch (args.command) {
+    case 'version':
+      cmdVersion(args);
+      break;
+    case 'branch':
+      cmdBranch(args);
+      break;
+    case 'crc32':
+      if (!args.string) {
+        console.log('ERROR: crc32 command requires a string argument');
+        process.exit(1);
+      }
+      cmdCrc32(args);
+      break;
+    case 'validate':
+      if (!args.message) {
+        console.log('ERROR: validate command requires a message argument');
+        process.exit(1);
+      }
+      cmdValidate(args);
+      break;
+    case 'check-monotonic':
+      cmdCheckMonotonic(args);
+      break;
+    case 'info':
+      cmdInfo(args);
+      break;
+    case 'versions':
+      cmdVersions(args);
+      break;
+    case 'verify':
+      cmdVerify(args);
+      break;
+    case 'tag':
+      cmdTag(args);
+      break;
+    default:
+      console.log(`Unknown command: ${args.command}`);
+      printUsage();
+      process.exit(1);
+  }
+}
+
+// Run if called directly
+if (process.argv[1] && process.argv[1].endsWith('cli.js')) {
+  main();
+}

package/src/config.js

@@ -0,0 +1,74 @@
+/**
+ * Configuration module for semver-ratchet.
+ *
+ * Handles all environment variable configuration:
+ * - RATCHET_GIT_PATH: Custom path to git binary
+ * - RATCHET_TRUNK_NAME: Custom name for main/trunk branch
+ * - RATCHET_DEFAULT_BUMP: Default version bump type
+ * - RATCHET_VERIFY_MINDEPTH: Minimum git history depth
+ * - RATCHET_MANUAL_VERSION: Manual version override (replaces RATCHET_OVERRIDE)
+ */
+
+/**
+ * Get the path to the git binary.
+ * @returns {string} Path to git binary (default: 'git')
+ */
+export function getGitPath() {
+  return process.env.RATCHET_GIT_PATH || 'git';
+}
+
+/**
+ * Get the name of the trunk/main branch.
+ * @returns {string} Name of the trunk branch (default: 'main')
+ */
+export function getTrunkName() {
+  return process.env.RATCHET_TRUNK_NAME || 'main';
+}
+
+/**
+ * Get the default version bump type.
+ * @returns {string} Default bump type: 'major', 'minor', or 'patch' (default: 'minor')
+ */
+export function getDefaultBump() {
+  return process.env.RATCHET_DEFAULT_BUMP || 'minor';
+}
+
+/**
+ * Get the minimum git history depth for verification.
+ * @returns {number} Minimum number of commits required (default: 50)
+ */
+export function getVerifyMinDepth() {
+  const depthStr = process.env.RATCHET_VERIFY_MINDEPTH;
+  if (depthStr !== undefined && depthStr !== null && depthStr !== '') {
+    const depth = parseInt(depthStr, 10);
+    if (!isNaN(depth) && depth >= 0) {
+      return depth;
+    }
+  }
+  return 50;
+}
+
+/**
+ * Get the manual version override.
+ * @returns {string|undefined} Manual version string or undefined
+ *
+ * Note: This replaces the deprecated RATCHET_OVERRIDE variable.
+ * RATCHET_OVERRIDE is still supported for backward compatibility.
+ */
+export function getManualVersion() {
+  // Check for new variable first
+  if (process.env.RATCHET_MANUAL_VERSION !== undefined &&
+      process.env.RATCHET_MANUAL_VERSION !== null &&
+      process.env.RATCHET_MANUAL_VERSION !== '') {
+    return process.env.RATCHET_MANUAL_VERSION;
+  }
+  
+  // Fallback to deprecated variable for backward compatibility
+  if (process.env.RATCHET_OVERRIDE !== undefined &&
+      process.env.RATCHET_OVERRIDE !== null &&
+      process.env.RATCHET_OVERRIDE !== '') {
+    return process.env.RATCHET_OVERRIDE;
+  }
+  
+  return undefined;
+}

package/src/git_adapter.js

@@ -0,0 +1,112 @@
+/**
+ * Git Adapter Interface for semver-ratchet.
+ *
+ * This module defines the interface that all git adapters must implement.
+ * Both RealGitAdapter and MockGitAdapter implement this interface.
+ */
+
+/**
+ * @typedef {Object} GitAdapter
+ * @property {function(): string} getCurrentBranch - Get the current branch name
+ * @property {function(): boolean} isMainBranch - Check if current branch is main/master
+ * @property {function(): number} getGitDistance - Get number of commits from main
+ * @property {function(): string|null} getLatestTag - Get the latest SemVer tag
+ * @property {function(): string[]} getCommitMessages - Get commit messages since tag
+ * @property {function(number): boolean} verifyGitHistory - Verify enough history exists
+ * @property {function(string): boolean} tagExists - Check if a tag exists
+ * @property {function(string, boolean): boolean} createTag - Create a git tag
+ * @property {function(string, string): void} pushTag - Push a tag to remote
+ */
+
+/**
+ * Abstract base class for Git adapters.
+ * All git adapter implementations must extend this class.
+ */
+export class GitAdapter {
+  /**
+   * Get the current branch name.
+   * @returns {string} The branch name
+   * @throws {Error} If git operation fails
+   */
+  getCurrentBranch() {
+    throw new Error('getCurrentBranch() must be implemented by subclass');
+  }
+
+  /**
+   * Check if current branch is main or master.
+   * @returns {boolean} True if on main/master branch
+   * @throws {Error} If git operation fails
+   */
+  isMainBranch() {
+    throw new Error('isMainBranch() must be implemented by subclass');
+  }
+
+  /**
+   * Get the number of commits between HEAD and main branch.
+   * @returns {number} Number of commits
+   * @throws {Error} If git operation fails
+   */
+  getGitDistance() {
+    throw new Error('getGitDistance() must be implemented by subclass');
+  }
+
+  /**
+   * Get the latest SemVer tag on the current branch.
+   * @returns {string|null} Tag version without 'v' prefix, or null if no tags
+   * @throws {Error} If git operation fails
+   */
+  getLatestTag() {
+    throw new Error('getLatestTag() must be implemented by subclass');
+  }
+
+  /**
+   * Get commit messages since a specific tag or all commits.
+   * @param {string} [_sinceTag] - Optional tag to start from (without 'v' prefix)
+   * @returns {string[]} List of commit messages
+   * @throws {Error} If git operation fails
+   */
+  getCommitMessages(_sinceTag = null) {
+    throw new Error('getCommitMessages() must be implemented by subclass');
+  }
+
+  /**
+   * Verify that enough git history is available.
+   * @param {number} [_fetchDepth] - Minimum number of commits required
+   * @returns {boolean} True if sufficient history exists
+   * @throws {Error} If history is insufficient
+   */
+  verifyGitHistory(_fetchDepth = 50) {
+    throw new Error('verifyGitHistory() must be implemented by subclass');
+  }
+
+  /**
+   * Check if a tag exists for the given version.
+   * @param {string} _version - Version string (without 'v' prefix)
+   * @returns {boolean} True if tag exists
+   * @throws {Error} If git operation fails
+   */
+  tagExists(_version) {
+    throw new Error('tagExists() must be implemented by subclass');
+  }
+
+  /**
+   * Create a git tag for the specified version.
+   * @param {string} _version - Version string (without 'v' prefix)
+   * @param {boolean} [_force] - If true, overwrite existing tag
+   * @returns {boolean} True if tag was created successfully
+   * @throws {Error} If git operation fails
+   */
+  createTag(_version, _force = false) {
+    throw new Error('createTag() must be implemented by subclass');
+  }
+
+  /**
+   * Push a tag to the remote repository.
+   * @param {string} _version - Version string (without 'v' prefix)
+   * @param {string} [_remote] - Remote name to push to
+   * @throws {Error} If git operation fails
+   */
+  pushTag(_version, _remote = 'origin') {
+    throw new Error('pushTag() must be implemented by subclass');
+  }
+}