semver-ratchet 1.0.0

package/README.md

@@ -0,0 +1,284 @@
+# semver-ratchet (Node.js)
+
+Node.js implementation of the semver-ratchet versioning system.
+
+## Prerequisites
+
+### Node.js Version Management (nvm)
+
+This project uses **nvm** (Node Version Manager) for managing Node.js versions.
+
+**Install nvm** (if not already installed):
+
+```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
+```
+
+**Install and use Node.js**:
+
+```bash
+# Install latest LTS version
+nvm install --lts
+
+# Set as default
+nvm use --lts
+
+# Verify installation
+node --version
+npm --version
+```
+
+**Project-specific Node.js version**:
+
+```bash
+# Create .nvmrc file with desired Node.js version
+echo "lts/*" > .nvmrc
+
+# Automatically use the correct version when entering project directory
+nvm use
+```
+
+## Installation
+
+### Development Setup
+
+```bash
+cd node
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+```
+
+### As a Package
+
+```bash
+npm install semver-ratchet
+```
+
+## Usage
+
+### As a Module
+
+```javascript
+import semverRatchet from 'semver-ratchet';
+
+// Get current version
+const version = semverRatchet.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);
+
+// Check if on main branch
+const isMain = semverRatchet.isMainBranch();
+console.log(isMain);
+
+// Calculate CRC32 of a string
+const crc = semverRatchet.calculateCrc32Unsigned('feature/my-branch');
+console.log(crc);
+
+// Create a git tag (main branch only)
+semverRatchet.createGitTag(version);
+
+// Push tag to remote
+semverRatchet.pushGitTag(version);
+```
+
+### CommonJS
+
+```javascript
+const semverRatchet = require('semver-ratchet');
+
+const version = semverRatchet.getVersion();
+console.log(version);
+```
+
+### CLI
+
+```bash
+# Get current version
+npx semver-ratchet version
+
+# Get current branch
+npx semver-ratchet branch
+
+# Calculate CRC32 hash
+npx semver-ratchet crc32 feature/my-branch
+
+# Validate commit message
+npx semver-ratchet validate "feat: add login [MINOR]"
+
+# Check version monotonicity
+npx semver-ratchet check-monotonic
+
+# Display versioning information
+npx semver-ratchet info
+
+# Generate compatible versions in CSV format
+npx semver-ratchet versions
+
+# Verify git history
+npx semver-ratchet verify
+
+# Create and push git tag
+npx semver-ratchet tag --push
+
+# With custom options
+npx semver-ratchet version --default-bump minor
+npx semver-ratchet tag --force --push --remote upstream
+```
+
+## API Reference
+
+### Functions
+
+#### `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
+
+#### `calculateFeatureVersion(verifyHistory?)`
+Calculate version for a feature branch.
+
+- **Returns:** string - Version in format "0.{CRC32}.{Distance}"
+
+#### `calculateMainVersion(defaultBump?, verifyHistory?)`
+Calculate version for main branch using SemVer.
+
+- **Returns:** string - Version in format "Major.Minor.Patch"
+
+#### `getCompatibleVersions(version)`
+Generate compatible version strings for dependency pinning.
+
+- **Parameters:**
+  - `version` (string): Full version string
+- **Returns:** string[] - Array of compatible versions
+
+#### `getCurrentBranch()`
+Get the current Git branch name.
+
+- **Returns:** string
+
+#### `isMainBranch()`
+Check if current branch is main or master.
+
+- **Returns:** boolean
+
+#### `calculateCrc32Unsigned(str)`
+Calculate CRC32 checksum as unsigned 32-bit integer.
+
+- **Parameters:**
+  - `str` (string): String to hash
+- **Returns:** number
+
+#### `parseSemver(version)`
+Parse a SemVer string into components.
+
+- **Parameters:**
+  - `version` (string): Version string
+- **Returns:** object - { major, minor, patch }
+
+#### `compareSemver(v1, v2)`
+Compare two SemVer versions.
+
+- **Parameters:**
+  - `v1` (string): First version
+  - `v2` (string): Second version
+- **Returns:** number - -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+
+#### `determineVersionBump(commitMessages, defaultBump?)`
+Determine version bump based on commit messages.
+
+- **Parameters:**
+  - `commitMessages` (string[]): List of commit messages
+  - `defaultBump` (string, optional): Default bump type
+- **Returns:** string - "major", "minor", or "patch"
+
+#### `createGitTag(version, force?)`
+Create a Git tag for the given version.
+
+- **Parameters:**
+  - `version` (string): Version string
+  - `force` (boolean, optional): Overwrite existing tag
+- **Returns:** boolean
+
+#### `pushGitTag(version, remote?)`
+Push a Git tag to remote repository.
+
+- **Parameters:**
+  - `version` (string): Version string
+  - `remote` (string, optional): Remote name (default: "origin")
+- **Returns:** boolean
+
+#### `verifyGitHistory(fetchDepth?)`
+Verify sufficient git history is available.
+
+- **Parameters:**
+  - `fetchDepth` (number, optional): Minimum commits required (default: 50)
+- **Returns:** boolean
+
+## Package.json Configuration
+
+Add to your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "semver-ratchet": "^0.2.0"
+  },
+  "scripts": {
+    "version": "semver-ratchet version",
+    "prepublish": "semver-ratchet tag --push"
+  }
+}
+```
+
+## Environment Variables
+
+- `RATCHET_OVERRIDE`: Override version completely (bypasses git). Useful for dev environments.
+
+```bash
+RATCHET_OVERRIDE=dev-local npx semver-ratchet version
+# Output: dev-local
+```
+
+## Testing
+
+### Run All Tests
+
+```bash
+npm test
+```
+
+### Run Tests in Watch Mode
+
+```bash
+npm run test:watch
+```
+
+### Run Specific Test File
+
+```bash
+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

package/bin/semver-ratchet

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main();

package/index.js

@@ -0,0 +1,29 @@
+/**
+ * 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).
+ */
+
+export {
+  getVersion,
+  calculateFeatureVersion,
+  calculateMainVersion,
+  getCurrentBranch,
+  isMainBranch,
+  calculateCrc32Unsigned,
+  verifyGitHistory,
+  parseSemver,
+  compareSemver,
+  getCompatibleVersions,
+  determineVersionBump,
+  createGitTag,
+  pushGitTag,
+  getBranch
+} from './src/version.js';
+
+export { main } from './src/cli.js';
+
+// Version of this package
+export const VERSION = '0.2.0';

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "semver-ratchet",
+  "version": "1.0.0",
+  "description": "Forward-only versioning for Trunk-Based Development",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "semver-ratchet": "./bin/semver-ratchet"
+  },
+  "scripts": {
+    "test": "node --test test/*.js",
+    "test:watch": "node --test --watch test/*.js",
+    "lint": "eslint src/ test/ bin/ --max-warnings 0",
+    "lint:fix": "eslint src/ test/ bin/ --fix",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "semver",
+    "versioning",
+    "git",
+    "trunk-based",
+    "ci/cd",
+    "ratchet"
+  ],
+  "author": "a-collet (https://github.com/a-collet)",
+  "contributors": [
+    "semver-ratchet contributors"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a-collet/semver-ratchet.git"
+  },
+  "bugs": {
+    "url": "https://github.com/a-collet/semver-ratchet/issues"
+  },
+  "homepage": "https://github.com/a-collet/semver-ratchet#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "index.js"
+  ],
+  "devDependencies": {
+    "eslint": "^10.1.0",
+    "eslint-config-google": "^0.14.0"
+  }
+}