feat: prospector improved greatly in terms of feedback, nonblocking and performance characteristics. Tested on repo with 3 million commits, works fine.

Author: RoenLie

COMMIT_SYNTAX.md

@@ -1,117 +1,149 @@
 # Commit Message Syntax for Version Bumping
 
-Prospector can automatically bump versions based on keywords in commit messages. This provides fine-grained control over versioning without requiring git tags for every release.
+Prospector can automatically bump versions based on simple keywords in commit messages. This provides fine-grained control over versioning without requiring git tags for every release.
 
 ## Supported Patterns
 
 ### Major Version Bumps
 
-Patterns that trigger a **major** version bump (e.g., `1.2.3` → `2.0.0`):
-
-- `[major]` - Explicit major bump marker
-- `+semver: major` - Semantic version annotation
-- `BREAKING CHANGE` - Conventional commits breaking change
-- `BREAKING-CHANGE` - Alternative format
+Use `[major]` to trigger a **major** version bump (e.g., `1.2.3` → `2.0.0`):
 
 **Examples:**
+
 ```bash
 git commit -m "[major] Complete API redesign"
-git commit -m "+semver: major - Removed legacy endpoints"
-git commit -m "refactor: BREAKING CHANGE: changed authentication flow"
+git commit -m "[major] Remove deprecated endpoints"
+git commit -m "Refactor authentication system [major]"
 ```
 
 ### Minor Version Bumps
 
-Patterns that trigger a **minor** version bump (e.g., `1.2.3` → `1.3.0`):
-
-- `[minor]` - Explicit minor bump marker
-- `+semver: minor` - Semantic version annotation
-- `feat:` - Conventional commits feature
-- `feature:` - Alternative feature marker
+Use `[minor]` to trigger a **minor** version bump (e.g., `1.2.3` → `1.3.0`):
 
 **Examples:**
+
 ```bash
 git commit -m "[minor] Add user dashboard"
-git commit -m "feat: implement dark mode"
-git commit -m "feature: add export to CSV functionality"
-git commit -m "+semver: minor - new reporting module"
+git commit -m "[minor] Implement dark mode"
+git commit -m "Add export to CSV functionality [minor]"
 ```
 
 ### Patch Version Bumps
 
-Patterns that trigger a **patch** version bump (e.g., `1.2.3` → `1.2.4`):
-
-- `[patch]` - Explicit patch bump marker
-- `+semver: patch` - Semantic version annotation
-- `fix:` - Conventional commits fix
-- `bugfix:` - Alternative fix marker
+Use `[patch]` to trigger a **patch** version bump (e.g., `1.2.3` → `1.2.4`):
 
 **Examples:**
+
 ```bash
 git commit -m "[patch] Update dependencies"
-git commit -m "fix: resolve login timeout issue"
-git commit -m "bugfix: correct date formatting"
-git commit -m "+semver: patch - minor UI tweaks"
+git commit -m "[patch] Fix login timeout issue"
+git commit -m "Correct date formatting [patch]"
+```
+
+### Explicit Version Setting
+
+Use `[version:x.y.z]` or `[v:x.y.z]` to set an **exact version**:
+
+**Examples:**
+
+```bash
+git commit -m "[version:1.5.0] Release version 1.5.0"
+git commit -m "[v:2.0.0] Major release"
+git commit -m "Prepare for release [version:1.2.3]"
 ```
 
+**Note:** When an explicit version is set, it takes precedence over any bump indicators. This is useful for:
+
+- Aligning with external version requirements
+- Jumping to a specific version number
+- Resetting version after major refactoring
+
 ### No Explicit Bump
 
 Commits without bump indicators fall back to the default behavior (commit count):
 
 **Examples:**
+
 ```bash
-git commit -m "chore: update README"
-git commit -m "docs: improve API documentation"
-git commit -m "style: format code"
-git commit -m "test: add unit tests"
+git commit -m "Update README"
+git commit -m "Refactor internal code"
+git commit -m "Add comments"
 ```
 
 ## Priority and Accumulation
 
 ### Priority Order
 
-When a commit contains multiple patterns, **only the highest priority** bump is counted:
+Patterns are evaluated in this priority order:
 
-1. **Major** (highest priority)
-2. **Minor**
-3. **Patch** (lowest priority)
+1. **Explicit version** (highest priority - `[version:x.y.z]`)
+2. **Major** (`[major]`)
+3. **Minor** (`[minor]`)
+4. **Patch** (`[patch]`)
+
+**Examples:**
 
-**Example:**
 ```bash
-# This commit only counts as a major bump, not major + minor
-git commit -m "feat: BREAKING CHANGE: new authentication system"
+# Explicit version takes precedence over everything
+git commit -m "[major] [version:3.5.0] Release 3.5.0"  # Results in 3.5.0
+
+# Only the highest bump counts per commit
+git commit -m "[major] [minor] Big change"  # Counts as major only
 ```
 
 ### Accumulation
 
 Multiple commits can accumulate bumps:
 
 **Scenario:**
+
 ```bash
 git tag v1.0.0
-git commit -m "feat: add feature A"     # Minor bump
-git commit -m "feat: add feature B"     # Minor bump
-git commit -m "fix: bug in feature A"   # Patch bump
+git commit -m "[minor] Add feature A"
+git commit -m "[minor] Add feature B"
+git commit -m "[patch] Fix bug in feature A"
 ```
 
 **Result:** Version `1.2.1`
+
 - Started at `1.0.0`
 - 2 minor bumps → `1.2.0`
 - 1 patch bump → `1.2.1`
 
+### Explicit Version Override
+
+When an explicit version is set, it overrides all accumulated bumps:
+
+**Scenario:**
+
+```bash
+git tag v1.0.0
+git commit -m "[minor] Add feature"     # Would bump to 1.1.0
+git commit -m "[version:2.5.0] Align with upstream"  # Sets to 2.5.0
+```
+
+**Result:** Version `2.5.0` (explicit version used)
+
 ### Version Reset Rules
 
 When bumping major or minor versions, lower components reset to 0:
 
 **Major bump:**
+
 - `1.5.7` + major → `2.0.0` (minor and patch reset)
 
 **Minor bump:**
+
 - `1.5.7` + minor → `1.6.0` (patch resets)
 
 **Patch bump:**
+
 - `1.5.7` + patch → `1.5.8` (no reset)
 
+**Explicit version:**
+
+- `1.5.7` + `[version:3.2.1]` → `3.2.1` (exact version)
+
 ## Customizing Patterns
 
 You can customize the patterns programmatically: