@exadev/build-identity 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Mearman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @exadev/build-identity
+
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/build-identity) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/@exadev/build-identity) [![Release](https://img.shields.io/github/v/release/ExaDev/build-identity)](https://github.com/ExaDev/build-identity/releases/latest) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/build-identity/ci.yml?branch=main)](https://github.com/ExaDev/build-identity/actions)
+
+> Resolve a build's true identity -- a real, already-tagged release, or the commit it was built from -- from live git state, with an optional predicted-version display layer.
+
+## Why
+
+A build banner or footer link (`v1.4.0`, linking to a release page) is only honest the moment a real release actually exists at that commit. Deriving that label from `package.json` alone, or from a CI environment variable, or from "this is the main branch so it must be the latest release" is exactly how a link to a release page that doesn't exist yet gets shipped -- typically the commit that triggers the release pipeline itself, before the tag and GitHub Release the link points at have actually been created. This package makes that check live and unavoidable: it shells out to git, checks whether the release tag genuinely points at `HEAD` right now, and only then returns a `'release'` identity.
+
+## Getting started
+
+```sh
+pnpm add -D @exadev/build-identity
+```
+
+```ts
+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' }
+// 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' }
+```
+
+## `resolveBuildIdentity(repoRoot, repoSlug, options?)`
+
+```ts
+type BuildIdentity =
+  | { kind: 'release'; version: string; url: string; date: string }
+  | { kind: 'commit'; version: string; url: string; date: string };
+
+function resolveBuildIdentity(repoRoot: string, repoSlug: string, options?: ResolveBuildIdentityOptions): BuildIdentity;
+
+interface ResolveBuildIdentityOptions {
+  tagName?: (version: string) => string; // defaults to (version) => `v${version}`
+}
+```
+
+- **`repoRoot`** -- path to the git working tree to inspect. Must contain `package.json` at its root; that file's `"version"` field is the released version this function checks for.
+- **`repoSlug`** -- the GitHub `"owner/repo"` slug used to build both the release and commit URLs (e.g. `"exadev/build-identity"`).
+- **`options.tagName`** -- turns the version into the tag name expected to mark its release. The default assumes the common `v<version>` convention (`"1.4.0"` -> `"v1.4.0"`); pass your own function for a repo that tags differently (a bare version, a package-scoped prefix in a monorepo, and so on).
+
+**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).
+
+`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)`
+
+```ts
+function resolvePredictedIdentity(build: BuildIdentity, predictedVersion: string | undefined): BuildIdentity & { predicted?: boolean };
+```
+
+An unreleased build's `version` is a short commit hash, which isn't always what you want to show a user -- often what's actually useful is *the version this commit will become once it releases*. This function lets a caller upgrade the displayed label to a predicted version (e.g. computed by running a commit-analyzer-style tool such as `semantic-release`'s own dry-run mode) without ever upgrading the URL to a release page that doesn't exist yet:
+
+- If `build.kind === 'release'`, it is returned **completely unchanged** -- a confirmed release always wins outright, prediction or not.
+- Otherwise, when `predictedVersion` is a real, non-empty string, the result's `version` becomes that (trimmed) prediction, `predicted` becomes `true`, and `url`/`date` are copied verbatim from `build` -- the link still points at the real commit.
+- With no usable prediction (`undefined`, empty, or whitespace-only), `build` is returned unchanged.
+
+This function does no git or filesystem access of its own -- computing the predicted version is entirely the caller's job, kept deliberately out of this package's core so the one property `resolveBuildIdentity` guarantees stays easy to audit on its own.
+
+```ts
+import { resolveBuildIdentity, resolvePredictedIdentity } from '@exadev/build-identity';
+
+const build = resolveBuildIdentity(process.cwd(), 'exadev/build-identity');
+const predictedVersion = await computeNextVersionSomehow(); // out of scope for this package
+const identity = resolvePredictedIdentity(build, predictedVersion);
+```
+
+## Framework-agnosticism
+
+This package does pure Node.js filesystem and git access only -- no bundler, framework, or UI assumptions. Wiring its result into a running app is a build-time concern for whichever bundler that app already uses, done in that bundler's own config file, not in this package.
+
+### Next.js
+
+```ts
+// next.config.ts
+import { resolveBuildIdentity } from '@exadev/build-identity';
+import type { NextConfig } from 'next';
+
+const buildIdentity = resolveBuildIdentity(process.cwd(), 'exadev/example');
+
+const config: NextConfig = {
+  env: {
+    NEXT_PUBLIC_BUILD_KIND: buildIdentity.kind,
+    NEXT_PUBLIC_BUILD_VERSION: buildIdentity.version,
+    NEXT_PUBLIC_BUILD_URL: buildIdentity.url,
+  },
+};
+
+export default config;
+```
+
+### Vite
+
+```ts
+// vite.config.ts
+import { resolveBuildIdentity } from '@exadev/build-identity';
+import { defineConfig } from 'vite';
+
+const buildIdentity = resolveBuildIdentity(process.cwd(), 'exadev/example');
+
+export default defineConfig({
+  define: {
+    __BUILD_KIND__: JSON.stringify(buildIdentity.kind),
+    __BUILD_VERSION__: JSON.stringify(buildIdentity.version),
+    __BUILD_URL__: JSON.stringify(buildIdentity.url),
+  },
+});
+```
+
+Either way, the values are inlined at build time -- the running app never shells out to git itself, and `resolveBuildIdentity`/`resolvePredictedIdentity` never ship as part of the app's own bundle.
+
+## Conventions
+
+British English throughout. Conventional commits, enforced by commitlint (`commitlint.config.ts`) and released automatically by `semantic-release` (`release.config.ts`) on every push to `main`. Strict TypeScript, no `any`, no type assertions -- see `eslint.config.ts`, which lints this package with `@exadev/eslint-config`.
+
+## Publishing
+
+Releases are handled entirely by `.github/workflows/ci.yml`'s `release` job: `semantic-release` analyses commits since the last tag, bumps the version, publishes to npmjs.org over OIDC trusted publishing (no stored `NPM_TOKEN`), and creates the tag and GitHub Release. See that workflow for the exact steps, and `CONTRIBUTING.md` for what a brand-new trusted-publish package needed once, by hand, before that automation could run unattended.

package/dist/index.cjs

@@ -0,0 +1,113 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let node_child_process = require("node:child_process");
+//#region src/git.ts
+function runGit(repoRoot, args) {
+	return (0, node_child_process.execFileSync)("git", args, {
+		cwd: repoRoot,
+		encoding: "utf8"
+	}).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.
+*/
+function getHeadCommit(repoRoot) {
+	return {
+		fullSha: runGit(repoRoot, ["rev-parse", "HEAD"]),
+		shortSha: runGit(repoRoot, [
+			"rev-parse",
+			"--short",
+			"HEAD"
+		]),
+		date: runGit(repoRoot, [
+			"log",
+			"-1",
+			"--format=%cI",
+			"HEAD"
+		])
+	};
+}
+/**
+* True only if `tagName` both exists and points at the exact commit HEAD is on right now. Uses `git tag --list <tag> --points-at HEAD`, which returns `tagName` itself when both hold and nothing otherwise -- there is no separate "tag exists but points elsewhere" case to confuse this with.
+*/
+function tagPointsAtHead(repoRoot, tagName) {
+	return runGit(repoRoot, [
+		"tag",
+		"--list",
+		tagName,
+		"--points-at",
+		"HEAD"
+	]).split("\n").map((line) => line.trim()).includes(tagName);
+}
+//#endregion
+//#region src/resolve-build-identity.ts
+const REPO_SLUG_PATTERN = /^[^/\s]+\/[^/\s]+$/;
+function defaultTagName(version) {
+	return `v${version}`;
+}
+function isPackageJsonWithVersion(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("version" in value)) return false;
+	return typeof value.version === "string" && value.version.length > 0;
+}
+function readPackageVersion(repoRoot) {
+	const packageJsonPath = (0, node_path.join)(repoRoot, "package.json");
+	const raw = (0, node_fs.readFileSync)(packageJsonPath, "utf8");
+	const parsed = JSON.parse(raw);
+	if (!isPackageJsonWithVersion(parsed)) throw new Error(`${packageJsonPath} must contain a non-empty string "version" field`);
+	return parsed.version;
+}
+function assertRepoSlug(repoSlug) {
+	if (!REPO_SLUG_PATTERN.test(repoSlug)) throw new Error(`repoSlug must be a GitHub "owner/repo" slug, got: ${JSON.stringify(repoSlug)}`);
+}
+/**
+* Resolves what the current build actually is: a real, already-tagged release, or a build made from a commit that hasn't been released yet.
+*
+* This is the one property the whole package exists to guarantee: `kind: 'release'` is returned if and only if a tag named `tagName(version)` (default `v${version}`) provably points at the exact commit HEAD is on right now, checked live against git -- never inferred from `package.json` alone, a CI environment variable, or any other proxy that could be true before the tag actually exists. A caller can render `url` as a link the moment it gets a result back, in either case, without first checking whether that link is real.
+*
+* @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root).
+* @param repoSlug The GitHub `owner/repo` slug used to build both release and commit URLs.
+*/
+function resolveBuildIdentity(repoRoot, repoSlug, options = {}) {
+	assertRepoSlug(repoSlug);
+	const version = readPackageVersion(repoRoot);
+	const tagName = (options.tagName ?? defaultTagName)(version);
+	const head = getHeadCommit(repoRoot);
+	if (tagPointsAtHead(repoRoot, tagName)) return {
+		kind: "release",
+		version,
+		url: `https://github.com/${repoSlug}/releases/tag/${tagName}`,
+		date: head.date
+	};
+	return {
+		kind: "commit",
+		version: head.shortSha,
+		url: `https://github.com/${repoSlug}/commit/${head.fullSha}`,
+		date: head.date
+	};
+}
+//#endregion
+//#region src/resolve-predicted-identity.ts
+/**
+* Upgrades an unreleased build's displayed version to a predicted one (e.g. the version a commit-analyzer-style tool computes the next release will be), without ever upgrading its URL.
+*
+* A confirmed release always wins outright: if `build.kind === 'release'`, this returns `build` completely unchanged, prediction or not -- a real, already-tagged release can never be second-guessed by a prediction. Otherwise, when `predictedVersion` is a real, non-empty string, the returned `version` becomes that predicted label, `predicted` becomes `true`, and `url` is copied verbatim from `build` -- it still points at the real commit, never at a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged.
+*
+* This function does no git or filesystem access of its own: predicting the next version (e.g. by running a commit-analyzer) is entirely the caller's job. It exists to keep that prediction, and the guarantee `resolveBuildIdentity` makes about `url`, cleanly separate.
+*/
+function resolvePredictedIdentity(build, predictedVersion) {
+	if (build.kind === "release") return build;
+	const trimmedPrediction = predictedVersion?.trim();
+	if (trimmedPrediction === void 0 || trimmedPrediction.length === 0) return build;
+	return {
+		kind: "commit",
+		version: trimmedPrediction,
+		url: build.url,
+		date: build.date,
+		predicted: true
+	};
+}
+//#endregion
+exports.resolveBuildIdentity = resolveBuildIdentity;
+exports.resolvePredictedIdentity = resolvePredictedIdentity;

package/dist/index.d.cts

@@ -0,0 +1,54 @@
+//#region src/types.d.ts
+/**
+ * What a build actually is, as far as git can prove it right now.
+ *
+ * A build is `'release'` only when a real, existing tag points at the exact commit being built -- never when a release is merely expected, scheduled, or about to happen. Every other build, including one sitting directly on top of the commit a release will eventually tag, is `'commit'`.
+ */
+type BuildIdentity = {
+  readonly kind: 'release';
+  /** The released version, read from `package.json` (e.g. `"1.4.0"`). */
+  readonly version: string;
+  /** The tag/release page for this exact version. */
+  readonly url: string;
+  /** ISO 8601 date of the commit this release was tagged at. */
+  readonly date: string;
+} | {
+  readonly kind: 'commit';
+  /** The short commit hash this build was made from -- there is no released version to show yet. */
+  readonly version: string;
+  /** The permalink to this exact commit. */
+  readonly url: string;
+  /** ISO 8601 date of this commit. */
+  readonly date: string;
+};
+interface ResolveBuildIdentityOptions {
+  /**
+   * Turns the version read from `package.json` into the git tag name that is expected to mark its release. Defaults to a `v` prefix (`"1.4.0"` -> `"v1.4.0"`), the convention this package's own release tooling and GitHub's own release UI both use -- override it for a repo that tags releases differently (a bare version, a package-scoped prefix in a monorepo, and so on).
+   */
+  readonly tagName?: (version: string) => string;
+}
+//#endregion
+//#region src/resolve-build-identity.d.ts
+/**
+ * Resolves what the current build actually is: a real, already-tagged release, or a build made from a commit that hasn't been released yet.
+ *
+ * This is the one property the whole package exists to guarantee: `kind: 'release'` is returned if and only if a tag named `tagName(version)` (default `v${version}`) provably points at the exact commit HEAD is on right now, checked live against git -- never inferred from `package.json` alone, a CI environment variable, or any other proxy that could be true before the tag actually exists. A caller can render `url` as a link the moment it gets a result back, in either case, without first checking whether that link is real.
+ *
+ * @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root).
+ * @param repoSlug The GitHub `owner/repo` slug used to build both release and commit URLs.
+ */
+declare function resolveBuildIdentity(repoRoot: string, repoSlug: string, options?: ResolveBuildIdentityOptions): BuildIdentity;
+//#endregion
+//#region src/resolve-predicted-identity.d.ts
+/**
+ * Upgrades an unreleased build's displayed version to a predicted one (e.g. the version a commit-analyzer-style tool computes the next release will be), without ever upgrading its URL.
+ *
+ * A confirmed release always wins outright: if `build.kind === 'release'`, this returns `build` completely unchanged, prediction or not -- a real, already-tagged release can never be second-guessed by a prediction. Otherwise, when `predictedVersion` is a real, non-empty string, the returned `version` becomes that predicted label, `predicted` becomes `true`, and `url` is copied verbatim from `build` -- it still points at the real commit, never at a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged.
+ *
+ * This function does no git or filesystem access of its own: predicting the next version (e.g. by running a commit-analyzer) is entirely the caller's job. It exists to keep that prediction, and the guarantee `resolveBuildIdentity` makes about `url`, cleanly separate.
+ */
+declare function resolvePredictedIdentity(build: BuildIdentity, predictedVersion: string | undefined): BuildIdentity & {
+  readonly predicted?: boolean;
+};
+//#endregion
+export { type BuildIdentity, type ResolveBuildIdentityOptions, resolveBuildIdentity, resolvePredictedIdentity };

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+//#region src/types.d.ts
+/**
+ * What a build actually is, as far as git can prove it right now.
+ *
+ * A build is `'release'` only when a real, existing tag points at the exact commit being built -- never when a release is merely expected, scheduled, or about to happen. Every other build, including one sitting directly on top of the commit a release will eventually tag, is `'commit'`.
+ */
+type BuildIdentity = {
+  readonly kind: 'release';
+  /** The released version, read from `package.json` (e.g. `"1.4.0"`). */
+  readonly version: string;
+  /** The tag/release page for this exact version. */
+  readonly url: string;
+  /** ISO 8601 date of the commit this release was tagged at. */
+  readonly date: string;
+} | {
+  readonly kind: 'commit';
+  /** The short commit hash this build was made from -- there is no released version to show yet. */
+  readonly version: string;
+  /** The permalink to this exact commit. */
+  readonly url: string;
+  /** ISO 8601 date of this commit. */
+  readonly date: string;
+};
+interface ResolveBuildIdentityOptions {
+  /**
+   * Turns the version read from `package.json` into the git tag name that is expected to mark its release. Defaults to a `v` prefix (`"1.4.0"` -> `"v1.4.0"`), the convention this package's own release tooling and GitHub's own release UI both use -- override it for a repo that tags releases differently (a bare version, a package-scoped prefix in a monorepo, and so on).
+   */
+  readonly tagName?: (version: string) => string;
+}
+//#endregion
+//#region src/resolve-build-identity.d.ts
+/**
+ * Resolves what the current build actually is: a real, already-tagged release, or a build made from a commit that hasn't been released yet.
+ *
+ * This is the one property the whole package exists to guarantee: `kind: 'release'` is returned if and only if a tag named `tagName(version)` (default `v${version}`) provably points at the exact commit HEAD is on right now, checked live against git -- never inferred from `package.json` alone, a CI environment variable, or any other proxy that could be true before the tag actually exists. A caller can render `url` as a link the moment it gets a result back, in either case, without first checking whether that link is real.
+ *
+ * @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root).
+ * @param repoSlug The GitHub `owner/repo` slug used to build both release and commit URLs.
+ */
+declare function resolveBuildIdentity(repoRoot: string, repoSlug: string, options?: ResolveBuildIdentityOptions): BuildIdentity;
+//#endregion
+//#region src/resolve-predicted-identity.d.ts
+/**
+ * Upgrades an unreleased build's displayed version to a predicted one (e.g. the version a commit-analyzer-style tool computes the next release will be), without ever upgrading its URL.
+ *
+ * A confirmed release always wins outright: if `build.kind === 'release'`, this returns `build` completely unchanged, prediction or not -- a real, already-tagged release can never be second-guessed by a prediction. Otherwise, when `predictedVersion` is a real, non-empty string, the returned `version` becomes that predicted label, `predicted` becomes `true`, and `url` is copied verbatim from `build` -- it still points at the real commit, never at a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged.
+ *
+ * This function does no git or filesystem access of its own: predicting the next version (e.g. by running a commit-analyzer) is entirely the caller's job. It exists to keep that prediction, and the guarantee `resolveBuildIdentity` makes about `url`, cleanly separate.
+ */
+declare function resolvePredictedIdentity(build: BuildIdentity, predictedVersion: string | undefined): BuildIdentity & {
+  readonly predicted?: boolean;
+};
+//#endregion
+export { type BuildIdentity, type ResolveBuildIdentityOptions, resolveBuildIdentity, resolvePredictedIdentity };

package/dist/index.js

@@ -0,0 +1,111 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+//#region src/git.ts
+function runGit(repoRoot, args) {
+	return execFileSync("git", args, {
+		cwd: repoRoot,
+		encoding: "utf8"
+	}).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.
+*/
+function getHeadCommit(repoRoot) {
+	return {
+		fullSha: runGit(repoRoot, ["rev-parse", "HEAD"]),
+		shortSha: runGit(repoRoot, [
+			"rev-parse",
+			"--short",
+			"HEAD"
+		]),
+		date: runGit(repoRoot, [
+			"log",
+			"-1",
+			"--format=%cI",
+			"HEAD"
+		])
+	};
+}
+/**
+* True only if `tagName` both exists and points at the exact commit HEAD is on right now. Uses `git tag --list <tag> --points-at HEAD`, which returns `tagName` itself when both hold and nothing otherwise -- there is no separate "tag exists but points elsewhere" case to confuse this with.
+*/
+function tagPointsAtHead(repoRoot, tagName) {
+	return runGit(repoRoot, [
+		"tag",
+		"--list",
+		tagName,
+		"--points-at",
+		"HEAD"
+	]).split("\n").map((line) => line.trim()).includes(tagName);
+}
+//#endregion
+//#region src/resolve-build-identity.ts
+const REPO_SLUG_PATTERN = /^[^/\s]+\/[^/\s]+$/;
+function defaultTagName(version) {
+	return `v${version}`;
+}
+function isPackageJsonWithVersion(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("version" in value)) return false;
+	return typeof value.version === "string" && value.version.length > 0;
+}
+function readPackageVersion(repoRoot) {
+	const packageJsonPath = join(repoRoot, "package.json");
+	const raw = readFileSync(packageJsonPath, "utf8");
+	const parsed = JSON.parse(raw);
+	if (!isPackageJsonWithVersion(parsed)) throw new Error(`${packageJsonPath} must contain a non-empty string "version" field`);
+	return parsed.version;
+}
+function assertRepoSlug(repoSlug) {
+	if (!REPO_SLUG_PATTERN.test(repoSlug)) throw new Error(`repoSlug must be a GitHub "owner/repo" slug, got: ${JSON.stringify(repoSlug)}`);
+}
+/**
+* Resolves what the current build actually is: a real, already-tagged release, or a build made from a commit that hasn't been released yet.
+*
+* This is the one property the whole package exists to guarantee: `kind: 'release'` is returned if and only if a tag named `tagName(version)` (default `v${version}`) provably points at the exact commit HEAD is on right now, checked live against git -- never inferred from `package.json` alone, a CI environment variable, or any other proxy that could be true before the tag actually exists. A caller can render `url` as a link the moment it gets a result back, in either case, without first checking whether that link is real.
+*
+* @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root).
+* @param repoSlug The GitHub `owner/repo` slug used to build both release and commit URLs.
+*/
+function resolveBuildIdentity(repoRoot, repoSlug, options = {}) {
+	assertRepoSlug(repoSlug);
+	const version = readPackageVersion(repoRoot);
+	const tagName = (options.tagName ?? defaultTagName)(version);
+	const head = getHeadCommit(repoRoot);
+	if (tagPointsAtHead(repoRoot, tagName)) return {
+		kind: "release",
+		version,
+		url: `https://github.com/${repoSlug}/releases/tag/${tagName}`,
+		date: head.date
+	};
+	return {
+		kind: "commit",
+		version: head.shortSha,
+		url: `https://github.com/${repoSlug}/commit/${head.fullSha}`,
+		date: head.date
+	};
+}
+//#endregion
+//#region src/resolve-predicted-identity.ts
+/**
+* Upgrades an unreleased build's displayed version to a predicted one (e.g. the version a commit-analyzer-style tool computes the next release will be), without ever upgrading its URL.
+*
+* A confirmed release always wins outright: if `build.kind === 'release'`, this returns `build` completely unchanged, prediction or not -- a real, already-tagged release can never be second-guessed by a prediction. Otherwise, when `predictedVersion` is a real, non-empty string, the returned `version` becomes that predicted label, `predicted` becomes `true`, and `url` is copied verbatim from `build` -- it still points at the real commit, never at a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged.
+*
+* This function does no git or filesystem access of its own: predicting the next version (e.g. by running a commit-analyzer) is entirely the caller's job. It exists to keep that prediction, and the guarantee `resolveBuildIdentity` makes about `url`, cleanly separate.
+*/
+function resolvePredictedIdentity(build, predictedVersion) {
+	if (build.kind === "release") return build;
+	const trimmedPrediction = predictedVersion?.trim();
+	if (trimmedPrediction === void 0 || trimmedPrediction.length === 0) return build;
+	return {
+		kind: "commit",
+		version: trimmedPrediction,
+		url: build.url,
+		date: build.date,
+		predicted: true
+	};
+}
+//#endregion
+export { resolveBuildIdentity, resolvePredictedIdentity };

package/package.json

@@ -1,5 +1,75 @@
 {
   "name": "@exadev/build-identity",
-  "version": "0.0.0",
-  "private": false
+  "version": "1.0.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,
+  "license": "MIT",
+  "packageManager": "pnpm@11.6.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "build-info",
+    "version",
+    "git",
+    "release",
+    "commit"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExaDev/build-identity.git"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@commitlint/cli": "21.2.1",
+    "@commitlint/config-conventional": "21.2.0",
+    "@exadev/eslint-config": "^2.10.4",
+    "@semantic-release/changelog": "7.0.0",
+    "@semantic-release/git": "11.0.1",
+    "@types/node": "24.13.3",
+    "@vitest/coverage-v8": "4.1.10",
+    "eslint": "10.8.0",
+    "husky": "9.1.7",
+    "lint-staged": "17.3.0",
+    "publint": "0.3.22",
+    "semantic-release": "25.0.8",
+    "tsdown": "0.22.14",
+    "turbo": "2.10.8",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.67.0",
+    "vitest": "4.1.10"
+  },
+  "scripts": {
+    "build": "turbo run _build",
+    "_build": "tsdown",
+    "lint": "turbo run _lint",
+    "_lint": "eslint . --fix --cache --max-warnings 0",
+    "typecheck": "turbo run _typecheck",
+    "_typecheck": "tsc -p tsconfig.json",
+    "test": "turbo run _test",
+    "_test": "vitest run",
+    "prepublishOnly": "pnpm run lint && pnpm run typecheck && pnpm run test && tsdown && publint && attw --pack",
+    "prepare": "husky",
+    "release": "semantic-release"
+  }
 }