sh3-core 0.16.0 → 0.16.1

package/dist/build.d.ts

@@ -36,7 +36,34 @@ export interface Sh3ArtifactOptions {
     serverEntry?: string;
     /** Override manifest fields not extractable from code (description, author, requires). */
     manifest?: Partial<Pick<ArtifactManifest, 'description' | 'author' | 'requires'>>;
+    /**
+     * Append a semver build-metadata suffix to the artifact `version` written
+     * into `manifest.json`. Per ADR-013 the package.json version remains the
+     * release-version source; this option layers an artifact-level counter on
+     * top so test iterations and hotfix variants of the same release can ship
+     * as distinct artifacts without bumping the release number.
+     *
+     *   - omit / undefined: artifact version equals package.json.version (default).
+     *   - 'auto': resolved from `git describe --tags --abbrev=0` →
+     *     `git rev-list --count <tag>..HEAD`. Suffix is omitted when the
+     *     count is 0 (canonical release) or when git is unavailable.
+     *   - string: literal suffix. Empty string is treated as no suffix.
+     *
+     * Example: package.json says "1.2.3", git is 4 commits past `v1.2.3` →
+     * manifest.json says `"version": "1.2.3+4"`.
+     */
+    buildSuffix?: 'auto' | string;
 }
+/**
+ * Compose a release version (`pkgVersion`) with an optional semver
+ * build-metadata suffix. Pure function — no I/O — for testability.
+ *
+ * Returns `pkgVersion` unchanged when `suffix` is empty/undefined.
+ * Throws when `pkgVersion` already carries build metadata or when the
+ * suffix is not a valid semver build-metadata identifier
+ * (dot-separated `[0-9A-Za-z-]+`).
+ */
+export declare function composeArtifactVersion(pkgVersion: string, suffix: string | undefined): string;
 /**
  * Vite plugin that produces a distributable artifact directory after build.
  *

package/dist/build.js

@@ -17,6 +17,7 @@
  *   });
  */
 import { readFileSync, writeFileSync, unlinkSync, readdirSync, copyFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
 import { join } from 'node:path';
 /**
  * Vite plugin that inlines extracted CSS into the JS bundle.
@@ -83,6 +84,52 @@ export function sh3CssInline() {
         },
     };
 }
+/**
+ * Compose a release version (`pkgVersion`) with an optional semver
+ * build-metadata suffix. Pure function — no I/O — for testability.
+ *
+ * Returns `pkgVersion` unchanged when `suffix` is empty/undefined.
+ * Throws when `pkgVersion` already carries build metadata or when the
+ * suffix is not a valid semver build-metadata identifier
+ * (dot-separated `[0-9A-Za-z-]+`).
+ */
+export function composeArtifactVersion(pkgVersion, suffix) {
+    if (!suffix)
+        return pkgVersion;
+    if (pkgVersion.includes('+')) {
+        throw new Error(`[sh3-artifact] package.json version "${pkgVersion}" already contains semver build metadata; cannot append additional suffix "${suffix}".`);
+    }
+    if (!/^[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*$/.test(suffix)) {
+        throw new Error(`[sh3-artifact] buildSuffix "${suffix}" is not a valid semver build-metadata identifier (expected dot-separated [0-9A-Za-z-]+).`);
+    }
+    return `${pkgVersion}+${suffix}`;
+}
+/**
+ * Resolve the auto build suffix from git: count of commits between the
+ * latest reachable tag and HEAD. Returns '' if git is unavailable, no
+ * tags exist, or HEAD is exactly at the tag (canonical release).
+ */
+function resolveAutoBuildSuffix() {
+    try {
+        const lastTag = execSync('git describe --tags --abbrev=0', {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (!lastTag)
+            return '';
+        const count = execSync(`git rev-list --count ${lastTag}..HEAD`, {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const n = parseInt(count, 10);
+        if (!Number.isFinite(n) || n <= 0)
+            return '';
+        return String(n);
+    }
+    catch (_a) {
+        return '';
+    }
+}
 /**
  * Vite plugin that produces a distributable artifact directory after build.
  *
@@ -224,6 +271,17 @@ export function sh3Artifact(options = {}) {
                 throw new Error('[sh3-artifact] Missing "version" in package.json. Per ADR-013 the package '
                     + 'version is read from package.json, not from the source manifest.');
             }
+            // --- Resolve build suffix and compose the artifact version ---
+            // Per ADR-013 amendment: package.json holds the release version;
+            // sh3Artifact may layer a build-metadata suffix on top.
+            let resolvedSuffix = '';
+            if (options.buildSuffix === 'auto') {
+                resolvedSuffix = resolveAutoBuildSuffix();
+            }
+            else if (typeof options.buildSuffix === 'string') {
+                resolvedSuffix = options.buildSuffix;
+            }
+            const artifactVersion = composeArtifactVersion(pkgVersion, resolvedSuffix);
             // --- Write manifest.json ---
             const overrides = (_c = options.manifest) !== null && _c !== void 0 ? _c : {};
             const finalDescription = (_d = overrides.description) !== null && _d !== void 0 ? _d : pkgDescription;
@@ -234,7 +292,7 @@ export function sh3Artifact(options = {}) {
             if (!finalAuthor) {
                 throw new Error('[sh3-artifact] Missing "author". Add it to package.json or pass it via sh3Artifact({ manifest: { author } }).');
             }
-            const manifest = Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: pkgVersion, contractVersion: 1, client: 'client.js' }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), overrides);
+            const manifest = Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: artifactVersion, contractVersion: 1, client: 'client.js' }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), overrides);
             writeFileSync(join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
             // --- Log summary ---
             const files = ['manifest.json', 'client.js'];

package/dist/build.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/build.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { composeArtifactVersion } from './build';
+describe('composeArtifactVersion', () => {
+    it('returns pkgVersion unchanged when suffix is undefined', () => {
+        expect(composeArtifactVersion('1.2.3', undefined)).toBe('1.2.3');
+    });
+    it('returns pkgVersion unchanged when suffix is empty string', () => {
+        expect(composeArtifactVersion('1.2.3', '')).toBe('1.2.3');
+    });
+    it('appends a numeric suffix as build metadata', () => {
+        expect(composeArtifactVersion('1.2.3', '42')).toBe('1.2.3+42');
+    });
+    it('appends dotted alphanumeric suffix as build metadata', () => {
+        expect(composeArtifactVersion('1.2.3', 'build.42')).toBe('1.2.3+build.42');
+    });
+    it('composes onto a prerelease version (semver allows -pre+meta)', () => {
+        expect(composeArtifactVersion('1.2.3-rc.1', '7')).toBe('1.2.3-rc.1+7');
+    });
+    it('throws when pkgVersion already has build metadata', () => {
+        expect(() => composeArtifactVersion('1.2.3+local', '42')).toThrow(/already contains semver build metadata/);
+    });
+    it('throws when suffix contains an invalid character', () => {
+        expect(() => composeArtifactVersion('1.2.3', 'build_42')).toThrow(/not a valid semver build-metadata identifier/);
+    });
+    it('throws when suffix has empty dot-separated identifier', () => {
+        expect(() => composeArtifactVersion('1.2.3', 'build..42')).toThrow(/not a valid semver build-metadata identifier/);
+    });
+    it('throws when suffix starts with a plus', () => {
+        expect(() => composeArtifactVersion('1.2.3', '+42')).toThrow(/not a valid semver build-metadata identifier/);
+    });
+});

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.16.0";
+export declare const VERSION = "0.16.1";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.16.0';
+export const VERSION = '0.16.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "type": "module",
   "files": [
     "dist"