fix: use semver-compliant dev version numbering (#479)

* fix: use semver-compliant dev version numbering

Change dev release scheme from MAJOR.MINOR.(PATCH+COMMITS)-dev.SHA
to MAJOR.MINOR.(PATCH+1)-dev.COMMITS. The old scheme inflated the
patch number (e.g. 3.1.49 for 45 commits after 3.1.4), colliding
with the real semver space. The new scheme keeps dev versions in the
correct prerelease range (e.g. 3.1.5-dev.45) — npm never picks them
up on plain install, they sort correctly, and the target release is
obvious.

Updated in publish.yml, scripts/bench-version.js, and dogfood skill.

Impact: 1 functions changed, 0 affected

* fix: align version computation between publish.yml and bench-version.js

- Add COMMITS=0 guard in publish.yml to return clean version when HEAD
  is exactly at a tag (mirrors bench-version.js early return)
- Change bench-version.js to use PATCH+1-dev.COMMITS format instead of
  PATCH+COMMITS-dev.SHA (mirrors publish.yml's new scheme)
- Fix fallback in bench-version.js to use dev.1 matching publish.yml's
  no-tags COMMITS=1 default

Impact: 1 functions changed, 0 affected

Author: carlos-alm

.claude/skills/dogfood/SKILL.md

@@ -24,7 +24,7 @@ Your goal is to install the published package, exercise every feature, compare e
    npm init -y && npm install @optave/codegraph@$ARGUMENTS
    ```
 
-   **Dev build** (version contains `-dev.`, e.g. `2.5.33-dev.3c36ef7`):
+   **Dev build** (version contains `-dev.`, e.g. `3.1.6-dev.12`):
    Dev builds are **not published to npm**. They are attached as tarballs to GitHub pre-releases. Install from the GitHub release:
    ```bash
    npm init -y

.github/workflows/publish.yml

@@ -67,8 +67,11 @@ jobs:
             NPM_TAG="latest"
             echo "Stable release (manual retry): $VERSION"
           else
-            # Use git describe to find the nearest release tag — same strategy
-            # as scripts/bench-version.js so versions are always consistent.
+            # Dev versions use the NEXT patch with a prerelease suffix:
+            #   v3.1.5 tag + 12 commits → 3.1.6-dev.12
+            # This keeps dev versions in the correct semver range (between
+            # the current release and the next) and avoids inflating the
+            # patch number (old scheme produced 3.1.17 for 12 commits after 3.1.5).
             RELEASE_TAG=$(git describe --tags --match "v*" --abbrev=0 2>/dev/null || echo "")
             if [ -n "$RELEASE_TAG" ]; then
               COMMITS=$(git rev-list "${RELEASE_TAG}..HEAD" --count)
@@ -77,9 +80,11 @@ jobs:
               COMMITS=1
               IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
             fi
-            DEV_PATCH=$((PATCH + COMMITS))
-            SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
-            VERSION="${MAJOR}.${MINOR}.${DEV_PATCH}-dev.${SHORT_SHA}"
+            if [ "$COMMITS" -eq 0 ]; then
+              VERSION="${MAJOR}.${MINOR}.${PATCH}"
+            else
+              VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))-dev.${COMMITS}"
+            fi
             NPM_TAG="dev"
             echo "Dev release: $VERSION (${COMMITS} commits since ${RELEASE_TAG:-none})"
           fi

scripts/bench-version.js

@@ -1,13 +1,14 @@
 /**
  * Compute the benchmark version string from git state.
  *
- * Uses the same two-step strategy as publish.yml's compute-version job:
+ * Uses the same strategy as publish.yml's compute-version job:
  *   1. `git describe --tags --match "v*" --abbrev=0` → find nearest release tag
  *   2. `git rev-list <tag>..HEAD --count` → count commits since that tag
  *
- * - If HEAD is exactly tagged (0 commits): returns "2.5.0"
- * - Otherwise: returns "2.5.N-dev.hash" (e.g. "2.5.3-dev.c50f7f5")
- *   where N = PATCH + commits since tag, hash = short commit SHA
+ * - If HEAD is exactly tagged (0 commits): returns "3.1.5"
+ * - Otherwise: returns "3.1.6-dev.12" (NEXT_PATCH-dev.COMMIT_COUNT)
+ *   This keeps dev versions in the correct semver range between the
+ *   current release and the next, avoiding inflated patch numbers.
  *
  * This prevents dev/dogfood benchmark runs from overwriting release data
  * in the historical benchmark reports (which deduplicate by version).
@@ -38,24 +39,18 @@ export function getBenchmarkVersion(pkgVersion, cwd) {
 		// Exact tag (0 commits since tag): return clean release version
 		if (commits === 0) return `${major}.${minor}.${patch}`;
 
-		// Dev build: MAJOR.MINOR.(PATCH+COMMITS)-dev.SHORT_SHA
-		const hash = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd, ...GIT_OPTS }).trim();
-		const devPatch = Number(patch) + commits;
-		return `${major}.${minor}.${devPatch}-dev.${hash}`;
+		// Dev build: MAJOR.MINOR.(PATCH+1)-dev.COMMITS
+		const nextPatch = Number(patch) + 1;
+		return `${major}.${minor}.${nextPatch}-dev.${commits}`;
 	} catch {
 		/* git not available or no tags */
 	}
 
-	// Fallback: no git or no tags — match publish.yml's no-tags behavior (PATCH+1-dev.SHA)
+	// Fallback: no git or no tags — match publish.yml's no-tags behavior (COMMITS=1)
 	const parts = pkgVersion.split('.');
 	if (parts.length === 3) {
 		const [major, minor, patch] = parts;
-		try {
-			const hash = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd, ...GIT_OPTS }).trim();
-			return `${major}.${minor}.${Number(patch) + 1}-dev.${hash}`;
-		} catch {
-			return `${major}.${minor}.${Number(patch) + 1}-dev`;
-		}
+		return `${major}.${minor}.${Number(patch) + 1}-dev.1`;
 	}
 	return `${pkgVersion}-dev`;
 }