@exadev/build-identity 1.0.0 → 1.1.0

package/README.md

@@ -18,17 +18,17 @@ pnpm add -D @exadev/build-identity
 import { resolveBuildIdentity } from '@exadev/build-identity';
 
 const identity = resolveBuildIdentity(process.cwd(), 'exadev/build-identity');
-// { kind: 'release', version: '1.4.0', url: 'https://github.com/exadev/build-identity/releases/tag/v1.4.0', date: '2026-09-08T09:12:03+01:00' }
+// { kind: 'release', version: '1.4.0', url: 'https://github.com/exadev/build-identity/releases/tag/v1.4.0', date: '2026-09-08T09:12:03+01:00', commit: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2' }
 // or, on any commit that isn't itself tagged:
-// { kind: 'commit', version: 'a1b2c3d', url: 'https://github.com/exadev/build-identity/commit/a1b2c3d4e5f6...', date: '2026-09-08T09:12:03+01:00' }
+// { kind: 'commit', version: 'a1b2c3d', url: 'https://github.com/exadev/build-identity/commit/a1b2c3d4e5f6...', date: '2026-09-08T09:12:03+01:00', commit: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2' }
 ```
 
 ## `resolveBuildIdentity(repoRoot, repoSlug, options?)`
 
 ```ts
 type BuildIdentity =
-  | { kind: 'release'; version: string; url: string; date: string }
-  | { kind: 'commit'; version: string; url: string; date: string };
+  | { kind: 'release'; version: string; url: string; date: string; commit: string }
+  | { kind: 'commit'; version: string; url: string; date: string; commit: string };
 
 function resolveBuildIdentity(repoRoot: string, repoSlug: string, options?: ResolveBuildIdentityOptions): BuildIdentity;
 
@@ -43,6 +43,8 @@ interface ResolveBuildIdentityOptions {
 
 **The one property this function exists to guarantee:** it returns `kind: 'release'` if, and only if, a tag named `tagName(version)` provably points at the exact commit `HEAD` is on right now -- checked live against git (`git tag --list <tag> --points-at HEAD`), never inferred from `package.json`, an environment variable, or any other proxy that could be true before the tag actually exists. Every other case, including a commit sitting directly on top of the commit a release will eventually tag, returns `kind: 'commit'` instead, with `version` set to the short commit hash (there is no released version to show yet) and `url` pointing at that exact commit's permalink (using the full SHA, not the short one, so the link stays a valid, unambiguous permalink).
 
+**`commit`** is always the full git commit SHA of the exact commit this build resolves to, in both branches -- present so a caller who needs the raw SHA (to compare two builds for identity, or to construct its own link) never has to parse it back out of `url`, which never carries one at all in the `'release'` case.
+
 `resolveBuildIdentity` throws rather than defaulting whenever it can't establish a real identity -- `repoRoot` isn't a git repository, `package.json` is missing or has no non-empty string `"version"` field, or `repoSlug` isn't a real `"owner/repo"` slug. There is no sensible placeholder identity for a build that isn't sitting in real, readable git history.
 
 ## `resolvePredictedIdentity(build, predictedVersion)`

package/dist/index.cjs

@@ -10,7 +10,7 @@ function runGit(repoRoot, args) {
 	}).trim();
 }
 /**
-* Reads HEAD's full hash, short hash, and committer date from the given git working tree. Throws whatever `git` itself throws (e.g. `repoRoot` is not a git repository, or has no commits) -- there is no sensible default identity for a build that isn't sitting in real git history.
+* Reads HEAD's full hash, short hash, and author date from the given git working tree. Author date, not committer date: a rebase-merged commit keeps its original author date but gets a fresh committer date at rebase time, and every consumer of this identity treats the date as "when this commit was authored", not "when it was last rewritten onto its current position". Throws whatever `git` itself throws (e.g. `repoRoot` is not a git repository, or has no commits) -- there is no sensible default identity for a build that isn't sitting in real git history.
 */
 function getHeadCommit(repoRoot) {
 	return {
@@ -23,7 +23,7 @@ function getHeadCommit(repoRoot) {
 		date: runGit(repoRoot, [
 			"log",
 			"-1",
-			"--format=%cI",
+			"--format=%aI",
 			"HEAD"
 		])
 	};
@@ -78,13 +78,15 @@ function resolveBuildIdentity(repoRoot, repoSlug, options = {}) {
 		kind: "release",
 		version,
 		url: `https://github.com/${repoSlug}/releases/tag/${tagName}`,
-		date: head.date
+		date: head.date,
+		commit: head.fullSha
 	};
 	return {
 		kind: "commit",
 		version: head.shortSha,
 		url: `https://github.com/${repoSlug}/commit/${head.fullSha}`,
-		date: head.date
+		date: head.date,
+		commit: head.fullSha
 	};
 }
 //#endregion
@@ -105,6 +107,7 @@ function resolvePredictedIdentity(build, predictedVersion) {
 		version: trimmedPrediction,
 		url: build.url,
 		date: build.date,
+		commit: build.commit,
 		predicted: true
 	};
 }

package/dist/index.d.cts

@@ -12,6 +12,8 @@ type BuildIdentity = {
   readonly url: string;
   /** ISO 8601 date of the commit this release was tagged at. */
   readonly date: string;
+  /** Full git commit SHA of the commit this release was tagged at -- the same commit `url` and `date` describe, exposed as its own field so a caller never has to parse it back out of a release URL that never contains one. */
+  readonly commit: string;
 } | {
   readonly kind: 'commit';
   /** The short commit hash this build was made from -- there is no released version to show yet. */
@@ -20,6 +22,8 @@ type BuildIdentity = {
   readonly url: string;
   /** ISO 8601 date of this commit. */
   readonly date: string;
+  /** Full git commit SHA this build was made from -- the same commit `version`'s short form and `url`'s permalink describe. */
+  readonly commit: string;
 };
 interface ResolveBuildIdentityOptions {
   /**

package/dist/index.d.ts

@@ -12,6 +12,8 @@ type BuildIdentity = {
   readonly url: string;
   /** ISO 8601 date of the commit this release was tagged at. */
   readonly date: string;
+  /** Full git commit SHA of the commit this release was tagged at -- the same commit `url` and `date` describe, exposed as its own field so a caller never has to parse it back out of a release URL that never contains one. */
+  readonly commit: string;
 } | {
   readonly kind: 'commit';
   /** The short commit hash this build was made from -- there is no released version to show yet. */
@@ -20,6 +22,8 @@ type BuildIdentity = {
   readonly url: string;
   /** ISO 8601 date of this commit. */
   readonly date: string;
+  /** Full git commit SHA this build was made from -- the same commit `version`'s short form and `url`'s permalink describe. */
+  readonly commit: string;
 };
 interface ResolveBuildIdentityOptions {
   /**

package/dist/index.js

@@ -9,7 +9,7 @@ function runGit(repoRoot, args) {
 	}).trim();
 }
 /**
-* Reads HEAD's full hash, short hash, and committer date from the given git working tree. Throws whatever `git` itself throws (e.g. `repoRoot` is not a git repository, or has no commits) -- there is no sensible default identity for a build that isn't sitting in real git history.
+* Reads HEAD's full hash, short hash, and author date from the given git working tree. Author date, not committer date: a rebase-merged commit keeps its original author date but gets a fresh committer date at rebase time, and every consumer of this identity treats the date as "when this commit was authored", not "when it was last rewritten onto its current position". Throws whatever `git` itself throws (e.g. `repoRoot` is not a git repository, or has no commits) -- there is no sensible default identity for a build that isn't sitting in real git history.
 */
 function getHeadCommit(repoRoot) {
 	return {
@@ -22,7 +22,7 @@ function getHeadCommit(repoRoot) {
 		date: runGit(repoRoot, [
 			"log",
 			"-1",
-			"--format=%cI",
+			"--format=%aI",
 			"HEAD"
 		])
 	};
@@ -77,13 +77,15 @@ function resolveBuildIdentity(repoRoot, repoSlug, options = {}) {
 		kind: "release",
 		version,
 		url: `https://github.com/${repoSlug}/releases/tag/${tagName}`,
-		date: head.date
+		date: head.date,
+		commit: head.fullSha
 	};
 	return {
 		kind: "commit",
 		version: head.shortSha,
 		url: `https://github.com/${repoSlug}/commit/${head.fullSha}`,
-		date: head.date
+		date: head.date,
+		commit: head.fullSha
 	};
 }
 //#endregion
@@ -104,6 +106,7 @@ function resolvePredictedIdentity(build, predictedVersion) {
 		version: trimmedPrediction,
 		url: build.url,
 		date: build.date,
+		commit: build.commit,
 		predicted: true
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exadev/build-identity",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Resolve a build's true identity (a real release tag, or the commit it was built from) from git state, with an optional predicted-version display layer",
   "type": "module",
   "sideEffects": false,