semver-ratchet 1.0.0 → 1.1.0

package/README.md

@@ -1,284 +1,256 @@
 # semver-ratchet (Node.js)
 
-Node.js implementation of the semver-ratchet versioning system.
+Node.js implementation of forward-only versioning for Trunk-Based Development.
 
-## Prerequisites
+## Dynamic Versioning
 
-### Node.js Version Management (nvm)
+semver-ratchet calculates versions dynamically from your git state.
 
-This project uses **nvm** (Node Version Manager) for managing Node.js versions.
+### Feature Branches: `0.{CRC32(branch_name)}.{GitDistance}`
 
-**Install nvm** (if not already installed):
+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.
 
-```bash
-# macOS / Linux
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
-
-# Then restart your terminal or run:
-source ~/.bashrc  # or ~/.zshrc for zsh
-```
+### Main Branch: `Major.Minor.Patch`
 
-**Install and use Node.js**:
+The main branch follows [Semantic Versioning 2.0.0](../docs/SEMVER.md). Bumps are determined by `[MAJOR]`, `[MINOR]`, or `[PATCH]` tags in commit messages.
 
-```bash
-# Install latest LTS version
-nvm install --lts
+### Dynamic Version in package.json
 
-# Set as default
-nvm use --lts
+Write version at build time:
 
-# Verify installation
-node --version
-npm --version
+```json
+{
+  "name": "your-project",
+  "version": "0.0.0-dynamic",
+  "scripts": {
+    "prebuild": "semver-ratchet version > .version",
+    "build": "node build.js"
+  }
+}
 ```
 
-**Project-specific Node.js version**:
+Or use it as a module:
 
-```bash
-# Create .nvmrc file with desired Node.js version
-echo "lts/*" > .nvmrc
+```javascript
+import { getVersion } from 'semver-ratchet';
 
-# Automatically use the correct version when entering project directory
-nvm use
+const version = getVersion();
+console.log(`Building version: ${version}`);
 ```
 
-## Installation
+---
 
-### Development Setup
+## Installation
 
 ```bash
-cd node
+npm install semver-ratchet
+```
 
-# Install dependencies
-npm install
+---
 
-# Run tests
-npm test
-```
+## Usage
 
-### As a Package
+### CLI
 
 ```bash
-npm install semver-ratchet
-```
+# Get current version
+npx semver-ratchet version
 
-## Usage
+# With custom trunk name
+npx semver-ratchet --trunk-name develop version
 
-### As a Module
+# 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
 
 ```javascript
-import semverRatchet from 'semver-ratchet';
+import {
+  getVersion,
+  getCompatibleVersions,
+  calculateCrc32Unsigned,
+  createGitTag,
+  pushGitTag,
+  isMainBranch,
+  getCurrentBranch,
+  verifyGitHistory,
+} from 'semver-ratchet';
 
 // Get current version
-const version = semverRatchet.getVersion();
+const version = getVersion();
 console.log(version);  // e.g., "1.0.0" or "0.12345678.5"
 
-// Get compatible versions for dependency pinning
-const compatible = semverRatchet.getCompatibleVersions(version);
-console.log(compatible);  // e.g., ["1.0.0", "1.0", "1"]
-
-// Get current branch
-const branch = semverRatchet.getBranch();
-console.log(branch);
+// With custom trunk name
+const version = getVersion("patch", true, "develop");
 
-// Check if on main branch
-const isMain = semverRatchet.isMainBranch();
-console.log(isMain);
+// 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 string
-const crc = semverRatchet.calculateCrc32Unsigned('feature/my-branch');
-console.log(crc);
+// Calculate CRC32 of a branch name
+const crc = calculateCrc32Unsigned('feature/my-branch');
 
 // Create a git tag (main branch only)
-semverRatchet.createGitTag(version);
+createGitTag(version);
 
 // Push tag to remote
-semverRatchet.pushGitTag(version);
+pushGitTag(version);
 ```
 
 ### CommonJS
 
 ```javascript
-const semverRatchet = require('semver-ratchet');
-
-const version = semverRatchet.getVersion();
-console.log(version);
+const { getVersion } = require('semver-ratchet');
+const version = getVersion();
 ```
 
-### CLI
+---
 
-```bash
-# Get current version
-npx semver-ratchet version
+## Configuration
 
-# Get current branch
-npx semver-ratchet branch
+### Config Precedence Chain
 
-# Calculate CRC32 hash
-npx semver-ratchet crc32 feature/my-branch
+```
+CLI flag  >  Environment variable  >  semver-ratchet.yaml  >  Default
+```
 
-# Validate commit message
-npx semver-ratchet validate "feat: add login [MINOR]"
+### CLI Flags
 
-# Check version monotonicity
-npx semver-ratchet check-monotonic
+| 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` |
 
-# Display versioning information
-npx semver-ratchet info
+### Environment Variables
 
-# Generate compatible versions in CSV format
-npx semver-ratchet versions
+| 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)* |
 
-# Verify git history
-npx semver-ratchet verify
+### Config File (`semver-ratchet.yaml`)
 
-# Create and push git tag
-npx semver-ratchet tag --push
+Place in your project root:
 
-# With custom options
-npx semver-ratchet version --default-bump minor
-npx semver-ratchet tag --force --push --remote upstream
+```yaml
+trunkName: main
+defaultBump: minor
+verifyMindepth: 50
+gitPath: /usr/local/bin/git
 ```
 
+---
+
 ## API Reference
 
-### Functions
+### `getVersion(defaultBump?, verifyHistory?, trunkName?)`
 
-#### `getVersion(defaultBump?, verifyHistory?)`
 Get the appropriate version based on current branch.
 
 - **Parameters:**
-  - `defaultBump` (string, optional): Default bump type - "major", "minor", or "patch" (default: "patch")
-  - `verifyHistory` (boolean, optional): Verify sufficient git history exists (default: true)
-- **Returns:** string - Version string
+  - `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?)`
 
-#### `calculateFeatureVersion(verifyHistory?)`
 Calculate version for a feature branch.
 
-- **Returns:** string - Version in format "0.{CRC32}.{Distance}"
+- **Returns:** `string` — `0.{CRC32}.{Distance}`
+
+### `calculateMainVersion(defaultBump?, verifyHistory?, trunkName?)`
 
-#### `calculateMainVersion(defaultBump?, verifyHistory?)`
 Calculate version for main branch using SemVer.
 
-- **Returns:** string - Version in format "Major.Minor.Patch"
+- **Returns:** `string` — `Major.Minor.Patch`
+
+### `getCompatibleVersions(version)`
 
-#### `getCompatibleVersions(version)`
 Generate compatible version strings for dependency pinning.
 
-- **Parameters:**
-  - `version` (string): Full version string
-- **Returns:** string[] - Array of compatible versions
+- **Returns:** `string[]`
+
+### `getCurrentBranch()`
 
-#### `getCurrentBranch()`
 Get the current Git branch name.
 
-- **Returns:** string
+- **Returns:** `string`
+
+### `isMainBranch(trunkName?)`
+
+Check if current branch is the trunk branch.
 
-#### `isMainBranch()`
-Check if current branch is main or master.
+- **Returns:** `boolean`
 
-- **Returns:** boolean
+### `calculateCrc32Unsigned(str)`
 
-#### `calculateCrc32Unsigned(str)`
 Calculate CRC32 checksum as unsigned 32-bit integer.
 
-- **Parameters:**
-  - `str` (string): String to hash
-- **Returns:** number
+- **Returns:** `number`
+
+### `parseSemver(version)`
 
-#### `parseSemver(version)`
 Parse a SemVer string into components.
 
-- **Parameters:**
-  - `version` (string): Version string
-- **Returns:** object - { major, minor, patch }
+- **Returns:** `{ major: number, minor: number, patch: number }`
 
-#### `compareSemver(v1, v2)`
-Compare two SemVer versions.
+### `compareSemver(v1, v2)`
 
-- **Parameters:**
-  - `v1` (string): First version
-  - `v2` (string): Second version
-- **Returns:** number - -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+Compare two SemVer versions.
 
-#### `determineVersionBump(commitMessages, defaultBump?)`
-Determine version bump based on commit messages.
+- **Returns:** `number` — `-1`, `0`, or `1`
 
-- **Parameters:**
-  - `commitMessages` (string[]): List of commit messages
-  - `defaultBump` (string, optional): Default bump type
-- **Returns:** string - "major", "minor", or "patch"
+### `determineVersionBump(commitMessages, defaultBump?)`
 
-#### `createGitTag(version, force?)`
-Create a Git tag for the given version.
+Determine version bump from commit messages.
 
-- **Parameters:**
-  - `version` (string): Version string
-  - `force` (boolean, optional): Overwrite existing tag
-- **Returns:** boolean
+- **Returns:** `string` — `"major"`, `"minor"`, or `"patch"`
 
-#### `pushGitTag(version, remote?)`
-Push a Git tag to remote repository.
+### `createGitTag(version, force?)`
 
-- **Parameters:**
-  - `version` (string): Version string
-  - `remote` (string, optional): Remote name (default: "origin")
-- **Returns:** boolean
+Create a Git tag for the given version.
 
-#### `verifyGitHistory(fetchDepth?)`
-Verify sufficient git history is available.
+- **Returns:** `boolean`
 
-- **Parameters:**
-  - `fetchDepth` (number, optional): Minimum commits required (default: 50)
-- **Returns:** boolean
+### `pushGitTag(version, remote?)`
 
-## Package.json Configuration
+Push a Git tag to remote repository.
 
-Add to your `package.json`:
+- **Returns:** `boolean`
 
-```json
-{
-  "dependencies": {
-    "semver-ratchet": "^0.2.0"
-  },
-  "scripts": {
-    "version": "semver-ratchet version",
-    "prepublish": "semver-ratchet tag --push"
-  }
-}
-```
+### `verifyGitHistory(fetchDepth?)`
 
-## Environment Variables
+Verify sufficient git history is available.
 
-- `RATCHET_OVERRIDE`: Override version completely (bypasses git). Useful for dev environments.
+- **Returns:** `boolean`
 
-```bash
-RATCHET_OVERRIDE=dev-local npx semver-ratchet version
-# Output: dev-local
-```
+---
 
 ## Testing
 
-### Run All Tests
-
 ```bash
+# Run all tests
 npm test
-```
-
-### Run Tests in Watch Mode
 
-```bash
-npm run test:watch
-```
-
-### Run Specific Test File
-
-```bash
+# Run specific test file
 node --test test/version.test.js
 ```
 
-**Note**: All tests use MockGitAdapter to avoid system git operations during testing, ensuring deterministic and isolated test results.
+---
 
 ## License
 
-MIT
+MIT License. See [LICENSE](../LICENSE) for details.

package/index.js

@@ -1,6 +1,6 @@
 /**
  * semver-ratchet: Forward-only versioning for Trunk-Based Development.
- * 
+ *
  * This module provides monotonic versioning based on Git history.
  * Feature branches use ephemeral versions (0.{CRC32}.{Distance}).
  * Main branch uses standard Semantic Versioning (Major.Minor.Patch).

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "semver-ratchet",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Forward-only versioning for Trunk-Based Development",
   "main": "index.js",
   "type": "module",
   "bin": {
-    "semver-ratchet": "./bin/semver-ratchet"
+    "semver-ratchet": "bin/semver-ratchet"
   },
   "scripts": {
     "test": "node --test test/*.js",
@@ -29,7 +29,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/a-collet/semver-ratchet.git"
+    "url": "git+https://github.com/a-collet/semver-ratchet.git"
   },
   "bugs": {
     "url": "https://github.com/a-collet/semver-ratchet/issues"

package/src/cli.js

@@ -24,6 +24,7 @@ function cmdVersion(_args) {
   const version = getVersion(
     _args.defaultBump || 'patch',
     !_args.noVerify,
+    _args.trunkName,
   );
   console.log(version);
   process.exit(0);
@@ -103,10 +104,11 @@ function cmdCheckMonotonic(_args) {
     const currentVersion = getVersion(
       _args.defaultBump || 'patch',
       !_args.noVerify,
+      _args.trunkName,
     );
 
     // For main branch, compare with latest tag
-    if (isMainBranch()) {
+    if (isMainBranch(_args.trunkName)) {
       try {
         const adapter = getGitAdapter();
         const latestTag = adapter.getLatestTag();
@@ -151,21 +153,23 @@ function cmdInfo(_args) {
   const version = getVersion(
     _args.defaultBump || 'patch',
     !_args.noVerify,
+    _args.trunkName,
   );
-  const branchType = isMainBranch() ? 'main' : 'feature';
+  const branchType = isMainBranch(_args.trunkName) ? 'main' : 'feature';
 
   console.log(`Branch: ${branch}`);
   console.log(`Type: ${branchType}`);
   console.log(`Version: ${version}`);
+  console.log(`Trunk name: ${_args.trunkName || 'main'}`);
   console.log(`Default bump: ${_args.defaultBump || 'patch'}`);
 
-  if (!isMainBranch()) {
+  if (!isMainBranch(_args.trunkName)) {
     const crc32 = calculateCrc32Unsigned(branch);
     console.log(`Branch CRC32: ${crc32}`);
   }
 
   // Show compatible versions for main branch
-  if (isMainBranch()) {
+  if (isMainBranch(_args.trunkName)) {
     try {
       parseSemver(version);
       const compatible = getCompatibleVersions(version);
@@ -187,6 +191,7 @@ function cmdVersions(_args) {
     const version = getVersion(
       _args.defaultBump || 'patch',
       !_args.noVerify,
+      _args.trunkName,
     );
 
     // Output as CSV
@@ -228,7 +233,7 @@ function cmdVerify(_args) {
  * @param {Object} _args - Command line arguments
  */
 function cmdTag(_args) {
-  if (!isMainBranch()) {
+  if (!isMainBranch(_args.trunkName)) {
     console.log('ERROR: Git tags can only be created on main branch');
     process.exit(1);
   }
@@ -259,6 +264,7 @@ function parseArgs(argv) {
     command: null,
     defaultBump: 'patch',
     noVerify: false,
+    trunkName: undefined,
   };
 
   const commands = ['version', 'branch', 'crc32', 'validate', 'check-monotonic', 'info', 'versions', 'verify', 'tag'];
@@ -281,6 +287,12 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--trunk-name') {
+      args.trunkName = argv[++i];
+      i++;
+      continue;
+    }
+
     if (arg === '--no-verify') {
       args.noVerify = true;
       i++;
@@ -352,6 +364,7 @@ Commands:
 
 Global Options:
   --default-bump <type>  Default version bump (major|minor|patch, default: patch)
+  --trunk-name <name>    Trunk branch name (default: main)
   --no-verify            Skip git history verification
 
 Tag Command Options:
@@ -365,6 +378,7 @@ Verify Command Options:
 Examples:
   semver-ratchet version
   semver-ratchet version --default-bump minor
+  semver-ratchet version --trunk-name develop
   semver-ratchet validate "feat: add login [MINOR]"
   semver-ratchet tag --push
   semver-ratchet crc32 feature/my-branch
@@ -428,4 +442,4 @@ export function main() {
 // Run if called directly
 if (process.argv[1] && process.argv[1].endsWith('cli.js')) {
   main();
-}
+}

package/src/config.js

@@ -1,7 +1,10 @@
 /**
  * Configuration module for semver-ratchet.
  *
- * Handles all environment variable configuration:
+ * Handles all configuration with precedence:
+ * CLI override > env var > config file > default
+ *
+ * Environment variables:
  * - RATCHET_GIT_PATH: Custom path to git binary
  * - RATCHET_TRUNK_NAME: Custom name for main/trunk branch
  * - RATCHET_DEFAULT_BUMP: Default version bump type
@@ -9,35 +12,64 @@
  * - RATCHET_MANUAL_VERSION: Manual version override (replaces RATCHET_OVERRIDE)
  */
 
+import { loadConfigFile } from './config_file.js';
+
+// Cache the loaded config file
+let cachedConfig = null;
+
+function getConfig() {
+  if (cachedConfig === null) {
+    cachedConfig = loadConfigFile();
+  }
+  return cachedConfig;
+}
+
 /**
  * Get the path to the git binary.
+ * @param {string} [cliOverride] - CLI override value
  * @returns {string} Path to git binary (default: 'git')
  */
-export function getGitPath() {
-  return process.env.RATCHET_GIT_PATH || 'git';
+export function getGitPath(cliOverride) {
+  if (cliOverride) return cliOverride;
+  if (process.env.RATCHET_GIT_PATH) return process.env.RATCHET_GIT_PATH;
+  const config = getConfig();
+  if (config && config.gitPath) return config.gitPath;
+  return 'git';
 }
 
 /**
  * Get the name of the trunk/main branch.
+ * @param {string} [cliOverride] - CLI override value
  * @returns {string} Name of the trunk branch (default: 'main')
  */
-export function getTrunkName() {
-  return process.env.RATCHET_TRUNK_NAME || 'main';
+export function getTrunkName(cliOverride) {
+  if (cliOverride) return cliOverride;
+  if (process.env.RATCHET_TRUNK_NAME) return process.env.RATCHET_TRUNK_NAME;
+  const config = getConfig();
+  if (config && config.trunkName) return config.trunkName;
+  return 'main';
 }
 
 /**
  * Get the default version bump type.
+ * @param {string} [cliOverride] - CLI override value
  * @returns {string} Default bump type: 'major', 'minor', or 'patch' (default: 'minor')
  */
-export function getDefaultBump() {
-  return process.env.RATCHET_DEFAULT_BUMP || 'minor';
+export function getDefaultBump(cliOverride) {
+  if (cliOverride) return cliOverride;
+  if (process.env.RATCHET_DEFAULT_BUMP) return process.env.RATCHET_DEFAULT_BUMP;
+  const config = getConfig();
+  if (config && config.defaultBump) return config.defaultBump;
+  return 'minor';
 }
 
 /**
  * Get the minimum git history depth for verification.
+ * @param {number} [cliOverride] - CLI override value (-1 for no override)
  * @returns {number} Minimum number of commits required (default: 50)
  */
-export function getVerifyMinDepth() {
+export function getVerifyMinDepth(cliOverride) {
+  if (cliOverride !== undefined && cliOverride >= 0) return cliOverride;
   const depthStr = process.env.RATCHET_VERIFY_MINDEPTH;
   if (depthStr !== undefined && depthStr !== null && depthStr !== '') {
     const depth = parseInt(depthStr, 10);
@@ -45,6 +77,8 @@ export function getVerifyMinDepth() {
       return depth;
     }
   }
+  const config = getConfig();
+  if (config && config.verifyMindepth > 0) return config.verifyMindepth;
   return 50;
 }
 
@@ -62,13 +96,13 @@ export function getManualVersion() {
       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/config_file.js

@@ -0,0 +1,98 @@
+/**
+ * Configuration file loader for semver-ratchet.
+ *
+ * Reads semver-ratchet.yaml from the project root and provides
+ * fallback configuration values.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+/**
+ * Find semver-ratchet.yaml by walking up from the current directory.
+ * @returns {string|null} Path to config file or null
+ */
+function findConfigFile() {
+  let dir = process.cwd();
+  while (true) {
+    const candidate = join(dir, 'semver-ratchet.yaml');
+    try {
+      if (statSync(candidate).isFile()) {
+        return candidate;
+      }
+    } catch {
+      // File doesn't exist, continue
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null; // Reached root
+    }
+    dir = parent;
+  }
+}
+
+/**
+ * Parse a simple YAML file (key: value format).
+ * @param {string} content - YAML content
+ * @returns {Object} Parsed config object
+ */
+function parseYAML(content) {
+  const config = {};
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    const idx = trimmed.indexOf(':');
+    if (idx >= 0) {
+      const key = trimmed.substring(0, idx).trim();
+      let value = trimmed.substring(idx + 1).trim();
+
+      // Strip quotes
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      config[key] = value;
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Load configuration from semver-ratchet.yaml.
+ * @returns {Object|null} Config object or null if file not found
+ */
+export function loadConfigFile() {
+  const path = findConfigFile();
+  if (!path) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(path, 'utf-8');
+    const config = parseYAML(content);
+
+    // Return null if no semver-ratchet keys found
+    if (!config.trunkName && !config.defaultBump &&
+        !config.verifyMindepth && !config.gitPath) {
+      return null;
+    }
+
+    // Normalize verifyMindepth to number
+    if (config.verifyMindepth) {
+      const depth = parseInt(config.verifyMindepth, 10);
+      config.verifyMindepth = isNaN(depth) ? 50 : depth;
+    }
+
+    return config;
+  } catch {
+    return null;
+  }
+}

package/src/git_adapter.js

@@ -34,19 +34,21 @@ export class GitAdapter {
 
   /**
    * Check if current branch is main or master.
+   * @param {string} [_trunkName] - Trunk branch name to check against
    * @returns {boolean} True if on main/master branch
    * @throws {Error} If git operation fails
    */
-  isMainBranch() {
+  isMainBranch(_trunkName) {
     throw new Error('isMainBranch() must be implemented by subclass');
   }
 
   /**
    * Get the number of commits between HEAD and main branch.
+   * @param {string} [_trunkName] - Trunk branch name
    * @returns {number} Number of commits
    * @throws {Error} If git operation fails
    */
-  getGitDistance() {
+  getGitDistance(_trunkName) {
     throw new Error('getGitDistance() must be implemented by subclass');
   }
 
@@ -109,4 +111,4 @@ export class GitAdapter {
   pushTag(_version, _remote = 'origin') {
     throw new Error('pushTag() must be implemented by subclass');
   }
-}
+}

package/src/git_mock.js

@@ -205,18 +205,25 @@ export class MockGitAdapter extends GitAdapter {
 
   /**
    * Check if current branch is main or master.
-   * @returns {boolean} True if on main/master branch
+   * @param {string} [trunkName] - Trunk branch name to check against
+   * @returns {boolean} True if on trunk branch
    */
-  isMainBranch() {
-    return this._currentBranch.toLowerCase() === 'main' || this._currentBranch.toLowerCase() === 'master';
+  isMainBranch(trunkName) {
+    if (trunkName) {
+      return this._currentBranch.toLowerCase() === trunkName.toLowerCase();
+    }
+    // Backward compatibility: check both main and master
+    return this._currentBranch.toLowerCase() === 'main' ||
+           this._currentBranch.toLowerCase() === 'master';
   }
 
   /**
-   * Calculate the number of commits between HEAD and main branch.
+   * Calculate the number of commits between HEAD and trunk branch.
+   * @param {string} [trunkName] - Trunk branch name
    * @returns {number} Number of commits
    */
-  getGitDistance() {
-    if (this.isMainBranch()) {
+  getGitDistance(trunkName) {
+    if (this.isMainBranch(trunkName)) {
       return 0;
     }
 
@@ -345,4 +352,4 @@ export class MockGitAdapter extends GitAdapter {
   getBranches() {
     return Object.keys(this._branches);
   }
-}
+}

package/src/git_real.js

@@ -39,28 +39,35 @@ export class RealGitAdapter extends GitAdapter {
 
   /**
    * Check if current branch is main or master.
-   * @returns {boolean} True if on main/master branch
+   * @param {string} [trunkName] - Trunk branch name to check against
+   * @returns {boolean} True if on trunk branch
    * @throws {Error} If git operation fails
    */
-  isMainBranch() {
+  isMainBranch(trunkName) {
     const branch = this.getCurrentBranch();
+    if (trunkName) {
+      return branch.toLowerCase() === trunkName.toLowerCase();
+    }
+    // Backward compatibility: check both main and master
     return branch.toLowerCase() === 'main' || branch.toLowerCase() === 'master';
   }
 
   /**
-   * Calculate the number of commits between HEAD and main branch.
+   * Calculate the number of commits between HEAD and trunk branch.
+   * @param {string} [trunkName] - Trunk branch name
    * @returns {number} Number of commits
    * @throws {Error} If git operation fails
    */
-  getGitDistance() {
-    if (this.isMainBranch()) {
+  getGitDistance(trunkName = 'main') {
+    const trunk = trunkName || 'main';
+    if (this.isMainBranch(trunk)) {
       return 0;
     }
 
     try {
-      // Count commits on current branch not on main
+      // Count commits on current branch not on trunk
       this.getCurrentBranch();
-      const output = execGit('rev-list --count HEAD ^origin/main 2>/dev/null || rev-list --count HEAD');
+      const output = execGit(`rev-list --count HEAD ^origin/${trunk} 2>/dev/null || rev-list --count HEAD`);
       return parseInt(output, 10) || 0;
     } catch {
       // Fallback: try a simpler approach
@@ -207,4 +214,4 @@ export class RealGitAdapter extends GitAdapter {
       throw new Error(`Failed to push tag: ${error.message}`);
     }
   }
-}
+}

package/src/version.js

@@ -6,7 +6,7 @@
  */
 
 import { RealGitAdapter } from './git_real.js';
-import { getManualVersion, getDefaultBump, getVerifyMinDepth } from './config.js';
+import { getManualVersion, getDefaultBump, getVerifyMinDepth, getTrunkName } from './config.js';
 
 // Global git adapter instance (can be overridden for testing)
 let _gitAdapter = null;
@@ -147,10 +147,12 @@ export function getCompatibleVersions(version) {
 
 /**
  * Check if current branch is main or master.
- * @returns {boolean} True if on main/master branch
+ * @param {string} [trunkNameOverride] - CLI override for trunk name
+ * @returns {boolean} True if on trunk branch
  */
-export function isMainBranch() {
-  return getGitAdapter().isMainBranch();
+export function isMainBranch(trunkNameOverride) {
+  const trunkName = trunkNameOverride !== undefined ? getTrunkName(trunkNameOverride) : undefined;
+  return getGitAdapter().isMainBranch(trunkName);
 }
 
 /**
@@ -204,14 +206,16 @@ export function determineVersionBump(messages, defaultBump = 'patch') {
  * Calculate the main branch version based on tags and commits.
  * @param {string} defaultBump - Default bump type (major|minor|patch)
  * @param {boolean} verifyHistory - Whether to verify git history
+ * @param {string} [trunkNameOverride] - CLI override for trunk name
  * @returns {string} SemVer version string
  * @throws {Error} If on feature branch or git operations fail
  */
-export function calculateMainVersion(defaultBump = 'patch', verifyHistory = true) {
+export function calculateMainVersion(defaultBump = 'patch', verifyHistory = true, trunkNameOverride) {
   const adapter = getGitAdapter();
+  const trunkName = trunkNameOverride !== undefined ? getTrunkName(trunkNameOverride) : undefined;
 
   // Verify we're on main branch
-  if (!adapter.isMainBranch()) {
+  if (!adapter.isMainBranch(trunkName)) {
     throw new Error('Cannot calculate main version on feature branch');
   }
 
@@ -258,20 +262,22 @@ export function calculateMainVersion(defaultBump = 'patch', verifyHistory = true
  * Calculate the feature branch version.
  * @param {string} _defaultBump - Default bump type (not used for feature branches)
  * @param {boolean} _verifyHistory - Whether to verify git history
+ * @param {string} [trunkNameOverride] - CLI override for trunk name
  * @returns {string} Feature version string (0.{CRC}.{Distance})
  * @throws {Error} If on main branch
  */
-export function calculateFeatureVersion(_defaultBump = 'patch', _verifyHistory = true) {
+export function calculateFeatureVersion(_defaultBump = 'patch', _verifyHistory = true, trunkNameOverride) {
   const adapter = getGitAdapter();
+  const trunkName = trunkNameOverride !== undefined ? getTrunkName(trunkNameOverride) : undefined;
 
   // Verify we're NOT on main branch
-  if (adapter.isMainBranch()) {
+  if (adapter.isMainBranch(trunkName)) {
     throw new Error('Cannot calculate feature version on main branch');
   }
 
   const branchName = adapter.getCurrentBranch();
   const crc = calculateCrc32Unsigned(branchName);
-  const distance = adapter.getGitDistance();
+  const distance = adapter.getGitDistance(trunkName);
 
   return `0.${crc}.${distance}`;
 }
@@ -280,9 +286,10 @@ export function calculateFeatureVersion(_defaultBump = 'patch', _verifyHistory =
  * Get the current version based on git state.
  * @param {string} [defaultBump] - Default bump type for main branch (uses env/config if not provided)
  * @param {boolean} [verifyHistory=true] - Whether to verify git history
+ * @param {string} [trunkNameOverride] - CLI override for trunk name
  * @returns {string} Version string
  */
-export function getVersion(defaultBump, _verifyHistory = true) {
+export function getVersion(defaultBump, _verifyHistory = true, trunkNameOverride) {
   // Check for manual version override first
   const manualVersion = getManualVersion();
   if (manualVersion !== undefined) {
@@ -295,11 +302,12 @@ export function getVersion(defaultBump, _verifyHistory = true) {
   }
 
   const adapter = getGitAdapter();
+  const trunkName = trunkNameOverride !== undefined ? getTrunkName(trunkNameOverride) : undefined;
 
-  if (adapter.isMainBranch()) {
-    return calculateMainVersion(defaultBump, _verifyHistory);
+  if (adapter.isMainBranch(trunkName)) {
+    return calculateMainVersion(defaultBump, _verifyHistory, trunkNameOverride);
   } else {
-    return calculateFeatureVersion(defaultBump, _verifyHistory);
+    return calculateFeatureVersion(defaultBump, _verifyHistory, trunkNameOverride);
   }
 }