semver-ratchet (Node.js)

Node.js implementation of forward-only versioning for Trunk-Based Development.

Dynamic Versioning

semver-ratchet calculates versions dynamically from your git state.

Feature Branches: 0.{CRC32(branch_name)}.{GitDistance}

Feature branches get ephemeral versions. The minor component is a CRC32 hash of the branch name, and the patch is the commit distance from the trunk branch.

Main Branch: Major.Minor.Patch

The main branch follows Semantic Versioning 2.0.0. Bumps are determined by [MAJOR], [MINOR], or [PATCH] tags in commit messages.

Dynamic Version in package.json

Write version at build time:

{
  "name": "your-project",
  "version": "0.0.0-dynamic",
  "scripts": {
    "prebuild": "semver-ratchet version > .version",
    "build": "node build.js"
  }
}

Or use it as a module:

import { getVersion } from 'semver-ratchet';

const version = getVersion();
console.log(`Building version: ${version}`);

Installation

npm install semver-ratchet

Usage

CLI

# Get current version
npx semver-ratchet version

# With custom trunk name
npx semver-ratchet --trunk-name develop version

# Skip git history verification
npx semver-ratchet --no-verify version

# Display versioning info
npx semver-ratchet info

# Create and push tag
npx semver-ratchet tag --push

ES Modules

import {
  getVersion,
  getCompatibleVersions,
  calculateCrc32Unsigned,
  createGitTag,
  pushGitTag,
  isMainBranch,
  getCurrentBranch,
  verifyGitHistory,
} from 'semver-ratchet';

// Get current version
const version = getVersion();
console.log(version);  // e.g., "1.0.0" or "0.12345678.5"

// With custom trunk name
const version = getVersion("patch", true, "develop");

// Get compatible versions for dependency pinning
const compatible = getCompatibleVersions("1.2.3");
console.log(compatible);  // ["1.2.3", "1.2", "1"]

// Calculate CRC32 of a branch name
const crc = calculateCrc32Unsigned('feature/my-branch');

// Create a git tag (main branch only)
createGitTag(version);

// Push tag to remote
pushGitTag(version);

CommonJS

const { getVersion } = require('semver-ratchet');
const version = getVersion();

Configuration

Config Precedence Chain

CLI flag  >  Environment variable  >  semver-ratchet.yaml  >  Default

CLI Flags

| Flag | Description | Default | | :--- | :--- | :--- | | --trunk-name <name> | Trunk branch name | main | | --default-bump {major,minor,patch} | Default bump type | patch | | --no-verify | Skip git history verification | false |

Environment Variables

| Variable | Description | Default | | :--- | :--- | :--- | | RATCHET_TRUNK_NAME | Trunk branch name | main | | RATCHET_DEFAULT_BUMP | Default bump type | minor | | RATCHET_GIT_PATH | Custom git binary path | git | | RATCHET_VERIFY_MINDEPTH | Minimum git history depth | 50 | | RATCHET_MANUAL_VERSION | Manual version override | (none) | | RATCHET_OVERRIDE | (deprecated) Same as above | (none) |

Config File (semver-ratchet.yaml)

Place in your project root:

trunkName: main
defaultBump: minor
verifyMindepth: 50
gitPath: /usr/local/bin/git

API Reference

getVersion(defaultBump?, verifyHistory?, trunkName?)

Get the appropriate version based on current branch.

• Parameters:
  • defaultBump (string, optional): Default bump type
  • verifyHistory (boolean, optional): Verify git history (default: true)
  • trunkName (string, optional): Trunk branch name override
• Returns: string

calculateFeatureVersion(verifyHistory?, trunkName?)

Calculate version for a feature branch.

• Returns: string — 0.{CRC32}.{Distance}

calculateMainVersion(defaultBump?, verifyHistory?, trunkName?)

Calculate version for main branch using SemVer.

• Returns: string — Major.Minor.Patch

getCompatibleVersions(version)

Generate compatible version strings for dependency pinning.

• Returns: string[]

getCurrentBranch()

Get the current Git branch name.

• Returns: string

isMainBranch(trunkName?)

Check if current branch is the trunk branch.

• Returns: boolean

calculateCrc32Unsigned(str)

Calculate CRC32 checksum as unsigned 32-bit integer.

• Returns: number

parseSemver(version)

Parse a SemVer string into components.

• Returns: { major: number, minor: number, patch: number }

compareSemver(v1, v2)

Compare two SemVer versions.

• Returns: number — -1, 0, or 1

determineVersionBump(commitMessages, defaultBump?)

Determine version bump from commit messages.

• Returns: string — "major", "minor", or "patch"

createGitTag(version, force?)

Create a Git tag for the given version.

• Returns: boolean

pushGitTag(version, remote?)

Push a Git tag to remote repository.

• Returns: boolean

verifyGitHistory(fetchDepth?)

Verify sufficient git history is available.

• Returns: boolean

Testing

# Run all tests
npm test

# Run specific test file
node --test test/version.test.js

License

MIT License. See LICENSE for details.