@exadev/build-identity 1.1.0 → 2.1.0

package/README.md

@@ -23,6 +23,8 @@ const identity = resolveBuildIdentity(process.cwd(), 'exadev/build-identity');
 // { kind: 'commit', version: 'a1b2c3d', url: 'https://github.com/exadev/build-identity/commit/a1b2c3d4e5f6...', date: '2026-09-08T09:12:03+01:00', commit: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2' }
 ```
 
+The same thing is available as a command, for build and deploy steps that cannot import anything -- see [`build-identity` (CLI)](#build-identity-cli).
+
 ## `resolveBuildIdentity(repoRoot, repoSlug, options?)`
 
 ```ts
@@ -50,29 +52,165 @@ interface ResolveBuildIdentityOptions {
 ## `resolvePredictedIdentity(build, predictedVersion)`
 
 ```ts
-function resolvePredictedIdentity(build: BuildIdentity, predictedVersion: string | undefined): BuildIdentity & { predicted?: boolean };
+type DisplayIdentity = { kind: 'release' | 'predicted' | 'commit'; version: string; url: string; date: string; commit: string };
+
+function resolvePredictedIdentity(build: BuildIdentity, predictedVersion: string | undefined): DisplayIdentity;
 ```
 
-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:
+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 `predictNextVersion`, below, or `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.
+- Otherwise, when `predictedVersion` is a real, non-empty string, the result is `kind: 'predicted'` with `version` set to that (trimmed) prediction -- `url`/`date`/`commit` are copied verbatim from `build`, still describing 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';
+import { resolveBuildIdentity, resolvePredictedIdentity, predictNextVersion, loadCommitAnalyzer } from '@exadev/build-identity';
+
+const build = resolveBuildIdentity(process.cwd(), 'exadev/build-identity');
+const predictedVersion = await predictNextVersion(process.cwd(), releaseRules, await loadCommitAnalyzer());
+const identity = resolvePredictedIdentity(build, predictedVersion);
+```
+
+## `predictNextVersion(repoRoot, releaseRules, analyzeCommits, options?)`
+
+```ts
+type ReleaseLevel = 'major' | 'minor' | 'patch';
+type ReleaseRule = { type: string; release: ReleaseLevel | false } | { breaking: true; release: ReleaseLevel | false };
+type AnalyzeCommits = (pluginConfig: unknown, context: unknown) => Promise<unknown>;
+
+function predictNextVersion(repoRoot: string, releaseRules: readonly ReleaseRule[], analyzeCommits: AnalyzeCommits, options?: PredictNextVersionOptions): Promise<string | undefined>;
+
+interface PredictNextVersionOptions {
+  tagName?: (version: string) => string; // matches resolveBuildIdentity's own option of the same name
+  logger?: { log: (...args: unknown[]) => void; error: (...args: unknown[]) => void }; // defaults to discarding
+}
+```
+
+Predicts the version a repo's next release would be, from the commits since its last tagged release -- **without** running `semantic-release`'s own top-level orchestrator. That orchestrator verifies push access to the remote as part of resolving branches before analysis ever runs, on every call, dry-run or not -- slow, and needing credentials a prediction has no real reason to hold. `predictNextVersion` instead calls `@semantic-release/commit-analyzer`'s own `analyzeCommits` hook directly: no network, no registry lookups, no push check.
+
+`releaseRules` is your own repo's commit-type-to-release-level convention (the same shape `@semantic-release/commit-analyzer`'s own `releaseRules` option takes) -- this package hardcodes none of its own.
+
+Returns `undefined` when there is genuinely no predicted release -- no commits since the last tag, or none of them are release-worthy -- the same "nothing to report" case `resolvePredictedIdentity` already treats as valid, not an error. Throws for a genuine setup problem instead of defaulting: `repoRoot` isn't a git repository, or `package.json` has no usable version.
+
+**`analyzeCommits`** is supplied by the caller rather than imported by this package: `@semantic-release/commit-analyzer` ships no type declarations and `analyzeCommits` isn't part of its documented public API, so loading it safely is a concern specific to your own toolchain. `predictNextVersion` itself stays a pure function of its arguments -- easy to test with a fake analyzer.
+
+## `loadCommitAnalyzer()`
+
+```ts
+function loadCommitAnalyzer(): Promise<AnalyzeCommits>;
+```
+
+The tested, correct way to obtain a real `analyzeCommits` for `predictNextVersion` above -- the one place in this package that actually loads `@semantic-release/commit-analyzer`. `@semantic-release/commit-analyzer` is an **optional peer dependency**: install it yourself if you use this function (or `predictNextVersion`); every other export in this package works without it. Throws a clear error, rather than a bare "Cannot find module", when it isn't installed or doesn't export `analyzeCommits`.
+
+```ts
+import { resolveBuildIdentity, resolvePredictedIdentity, predictNextVersion, loadCommitAnalyzer } from '@exadev/build-identity';
+
+const releaseRules = [
+  { breaking: true, release: 'major' },
+  { type: 'feat', release: 'minor' },
+  { type: 'fix', release: 'patch' },
+];
 
 const build = resolveBuildIdentity(process.cwd(), 'exadev/build-identity');
-const predictedVersion = await computeNextVersionSomehow(); // out of scope for this package
+const predictedVersion = await predictNextVersion(process.cwd(), releaseRules, await loadCommitAnalyzer());
 const identity = resolvePredictedIdentity(build, predictedVersion);
 ```
 
+## `build-identity` (CLI)
+
+The same three functions, wired together, as a command. It exists for build and deploy steps that are a shell invocation rather than a JavaScript config file, so nothing in them can `import` this package at all -- `wrangler deploy --var RELEASE_VERSION:...` being the case it was built for. A step that *is* a JavaScript config file (`next.config.ts`, `vite.config.ts`) should import the functions directly instead; see [Framework-agnosticism](#framework-agnosticism) below.
+
+```sh
+pnpm add -D @exadev/build-identity
+pnpm exec build-identity --repo exadev/build-identity
+```
+
+```
+Usage: build-identity [options]
+
+Options:
+  -V, --version                output the version number
+  --repo <owner/repo>          GitHub slug used to build the release and commit URLs
+  --root <directory>           git working tree to inspect (default: the current working directory)
+  --tag-name <template>        tag name marking a release, with {version} standing in for the version (default: v{version})
+  --predict                    also predict the version this commit's next release would be
+  --release-rules <json>       commit-analyzer release rules for --predict, as a JSON array
+  --release-rules-file <path>  file holding the same JSON array as --release-rules
+  --format <format>            output format: json or env (default: "json")
+  --prefix <prefix>            prepended to each variable name in --format env (default: "BUILD_")
+  --verbose                    send commit-analyzer's own per-commit narration to stderr
+  -h, --help                   display help for command
+```
+
+`--repo` is the only required flag, and the command's whole output is a single `DisplayIdentity` on stdout:
+
+```sh
+$ build-identity --repo exadev/build-identity
+{
+  "kind": "commit",
+  "version": "a1b2c3d",
+  "url": "https://github.com/exadev/build-identity/commit/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
+  "date": "2026-09-08T09:12:03+01:00",
+  "commit": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+}
+```
+
+Those are exactly the five fields `DisplayIdentity` declares, under exactly its own names -- there is no CLI-specific shape and no consumer-specific naming. In particular there is no separate `predicted` boolean: `kind` is already `"predicted"` in precisely that case, and a second field asserting the same fact would just be one more thing that could disagree with the first.
+
+### Prediction
+
+`--predict` adds the `predictNextVersion` step, turning an unreleased build's short commit hash into the version that commit would release as. It is opt-in rather than automatic because it costs something real: it needs `@semantic-release/commit-analyzer` (this package's optional peer dependency) to be installed, and it reads every commit since the last tag.
+
+Release rules are yours, not this package's -- your repo's commit-type-to-release-level convention is real configuration, and nothing here invents a default for it. Pass them inline, or from a file when quoting a full rule set through YAML and a shell gets unreadable:
+
+```sh
+build-identity --repo exadev/build-identity --predict \
+  --release-rules '[{"breaking":true,"release":"major"},{"type":"feat","release":"minor"},{"type":"fix","release":"patch"}]'
+
+build-identity --repo exadev/build-identity --predict --release-rules-file release-rules.json
+```
+
+A confirmed release still wins outright: on a commit an actual release tag points at, `--predict` changes nothing at all.
+
+### `--format env`
+
+```sh
+$ build-identity --repo exadev/build-identity --format env --prefix RELEASE_
+RELEASE_KIND=commit
+RELEASE_VERSION=a1b2c3d
+RELEASE_URL=https://github.com/exadev/build-identity/commit/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
+RELEASE_DATE=2026-09-08T09:12:03+01:00
+RELEASE_COMMIT=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
+```
+
+The variable names are the same generic field names, upper-cased, behind a prefix of your choosing. This format is deliberately additional surface rather than "emit JSON and document a `jq` one-liner": appending to `$GITHUB_ENV` is the realistic use for both of the cases that motivated this CLI, and the one-liner alternative would put a `jq` dependency and a quoting-sensitive shell expression into every consumer's workflow to produce output this package can simply print. A value containing a line break is refused outright rather than emitted, since it would silently swallow or inject `$GITHUB_ENV` entries.
+
+```yaml
+- name: Resolve the build's identity
+  run: pnpm exec build-identity --repo my-org/my-repo --predict --release-rules-file release-rules.json --format env --prefix RELEASE_ >> "$GITHUB_ENV"
+
+- name: Deploy
+  run: wrangler deploy --var RELEASE_VERSION:$RELEASE_VERSION --var RELEASE_COMMIT:$RELEASE_COMMIT
+```
+
+Where a repo's own variable names differ from the generic ones, map them in that repo's own workflow rather than expecting this package to know them -- `--prefix` covers most of it, and `jq` covers the rest:
+
+```sh
+echo "MY_OWN_VERSION_NAME=$(build-identity --repo my-org/my-repo | jq -r .version)" >> "$GITHUB_ENV"
+```
+
+`--verbose` routes commit-analyzer's own per-commit narration to **stderr**, never stdout, so it is always safe to pipe or capture stdout while debugging why a prediction came out as it did.
+
+The CLI is the one part of this package with a runtime dependency (`commander`, itself dependency-free). It is bundled into `dist/cli.js` alone: importing the library never loads it. It stays on `commander@14` deliberately, rather than the newest major: `commander@15` raises its own floor to Node 22.12, which would contradict this package's declared `engines` of Node 20 and upwards. Raise it alongside that floor, not before it.
+
 ## 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.
 
+**A config file that is itself JavaScript does not need the CLI** -- it can import the functions directly, which is both simpler and better typed than shelling out and parsing JSON back. Reach for `build-identity` (above) only where there is genuinely nothing to import from: a `wrangler deploy --var ...` line, a `docker build --build-arg ...` line, a plain `sh` deploy script.
+
 ### Next.js
 
 ```ts
@@ -111,7 +249,7 @@ export default defineConfig({
 });
 ```
 
-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.
+Either way, the values are inlined at build time -- the running app never shells out to git itself, and `resolveBuildIdentity`/`resolvePredictedIdentity`/`predictNextVersion`/`loadCommitAnalyzer` never ship as part of the app's own bundle.
 
 ## Conventions
 

package/dist/cli.js

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { format } from "node:util";
+import { Command, InvalidArgumentError, Option } from "commander";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+//#region package.json
+var version = "2.1.0";
+//#endregion
+//#region src/format-identity.ts
+const OUTPUT_FORMATS = ["json", "env"];
+function isOutputFormat(value) {
+	return value === "json" || value === "env";
+}
+/** Every field of `DisplayIdentity`, in the order it is declared there. The `env` format derives its variable names by upper-casing these directly, so there is no second name mapping that could drift out of step with the type itself. */
+const IDENTITY_FIELDS = [
+	"kind",
+	"version",
+	"url",
+	"date",
+	"commit"
+];
+/** A prefix is glued straight onto an already-upper-case field name, so it only has to keep the result a legal shell/GitHub Actions variable name. An empty prefix is legitimate (bare `KIND=`, `VERSION=`, ...) for a caller that genuinely wants the unprefixed names. */
+const ENV_PREFIX_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$|^$/;
+function isEnvPrefix(value) {
+	return ENV_PREFIX_PATTERN.test(value);
+}
+/**
+* Renders a resolved identity for stdout, in whichever of the two formats the caller asked for.
+*
+* `json` emits the `DisplayIdentity` object verbatim -- the same five field names the library's own type declares, with no CLI-invented additions. In particular there is no separate `predicted` boolean: `kind` is already `'predicted'` in exactly that case, and a second field asserting the same fact would be one more thing every writer has to keep in step.
+*
+* `env` emits one `PREFIX_FIELD=value` line per field, upper-cased, ready to append straight to `$GITHUB_ENV` (or `eval`/`source` in a plain shell). Each repo maps these generic names onto whatever it calls them itself; this package never emits a consumer-specific name.
+*/
+function formatIdentity(identity, options) {
+	if (options.format === "json") return JSON.stringify(identity, null, 2);
+	if (!isEnvPrefix(options.prefix)) throw new Error(`--prefix must be empty or a legal variable-name prefix ([A-Za-z_][A-Za-z0-9_]*), got: ${JSON.stringify(options.prefix)}`);
+	return IDENTITY_FIELDS.map((field) => {
+		const value = identity[field];
+		if (/[\r\n]/.test(value)) throw new Error(`${field} contains a line break, which cannot be represented as a KEY=VALUE line: ${JSON.stringify(value)}`);
+		return `${options.prefix}${field.toUpperCase()}=${value}`;
+	}).join("\n");
+}
+//#endregion
+//#region src/load-commit-analyzer.ts
+const COMMIT_ANALYZER_SPECIFIER = "@semantic-release/commit-analyzer";
+function hasAnalyzeCommits(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("analyzeCommits" in value)) return false;
+	return typeof value.analyzeCommits === "function";
+}
+/**
+* Loads `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- the tested, correct way to obtain the `AnalyzeCommits` implementation `predictNextVersion` (`./predict-next-version`) needs. Split out from `predictNextVersion` itself so that function stays a pure, easily-fakeable function of its own arguments; this is the one place in the package that actually touches the untyped module.
+*
+* `@semantic-release/commit-analyzer` is an optional peer dependency (see this package's own `package.json`): not required to use `resolveBuildIdentity`/`resolvePredictedIdentity`, only to call this function. Throws a clear error, rather than a bare "Cannot find module", when it isn't installed or doesn't export `analyzeCommits` -- a version bump of the real package removing or renaming that export fails loudly here, not silently.
+*/
+async function loadCommitAnalyzer() {
+	let commitAnalyzerModule;
+	try {
+		commitAnalyzerModule = await import(COMMIT_ANALYZER_SPECIFIER);
+	} catch (error) {
+		throw new Error("@semantic-release/commit-analyzer is not installed -- it is an optional peer dependency of @exadev/build-identity, required only for loadCommitAnalyzer/predictNextVersion.", { cause: error });
+	}
+	if (!hasAnalyzeCommits(commitAnalyzerModule)) throw new Error("@semantic-release/commit-analyzer has no analyzeCommits export.");
+	return commitAnalyzerModule.analyzeCommits;
+}
+//#endregion
+//#region src/package-version.ts
+/** Turns a version into the tag name expected to mark its release -- the shared default (and shared option shape) both `resolveBuildIdentity` and `predictNextVersion` accept, so a repo that tags differently only has to say so once per call site, not maintain two independent conventions. */
+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;
+}
+/** The single semantic-release-managed version, read from `package.json` at `repoRoot`'s root -- shared by `resolveBuildIdentity` (what this build's version is, if released) and `predictNextVersion` (the version to diff commits since). Throws rather than defaulting, matching this package's own "no sensible placeholder identity" stance. */
+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;
+}
+//#endregion
+//#region src/predict-next-version.ts
+const GIT_FORMAT = "%x00%H%x00%B";
+const FIELD_SEP = "\0";
+/**
+* Pure parsing of `git log --format=%x00%H%x00%B` output -- split out so it's testable against a raw string fixture with no real git process. NUL is git's own pretty-format escape for a real NUL byte, the one byte git guarantees can never appear inside a commit hash or message (git refuses to store one), making it the only delimiter genuinely safe against arbitrary commit content. Each record is `<hash><NUL><message>`, with a leading NUL on the whole format string, so splitting the entire raw output on NUL and dropping the resulting leading empty token leaves an exact (hash, message) pairing for every commit. Git appends its own trailing newline per record (tformat behaviour); trim() absorbs it the same way it absorbs genuine trailing blank lines in a real commit body.
+*/
+function parseGitLogOutput(raw) {
+	const tokens = raw.split(FIELD_SEP);
+	tokens.shift();
+	const commits = [];
+	for (let index = 0; index < tokens.length; index += 2) commits.push({
+		hash: tokens[index] ?? "",
+		message: (tokens[index + 1] ?? "").trim()
+	});
+	return commits;
+}
+function readCommitsSince(repoRoot, sinceTag) {
+	return parseGitLogOutput(execFileSync("git", [
+		"log",
+		`${sinceTag}..HEAD`,
+		`--format=${GIT_FORMAT}`
+	], {
+		cwd: repoRoot,
+		encoding: "utf-8"
+	}));
+}
+function isReleaseLevel(value) {
+	return value === "major" || value === "minor" || value === "patch";
+}
+/** A trivial major.minor.patch increment -- every version this package works with is a plain X.Y.Z, never a prerelease or build-metadata identifier (see `resolveBuildIdentity`'s own tag convention), so there is no broader semver grammar here worth delegating to a library for. */
+function bumpVersion(version, releaseType) {
+	const [major = 0, minor = 0, patch = 0] = version.split(".").map(Number);
+	if (releaseType === "major") return `${String(major + 1)}.0.0`;
+	if (releaseType === "minor") return `${String(major)}.${String(minor + 1)}.0`;
+	return `${String(major)}.${String(minor)}.${String(patch + 1)}`;
+}
+const NOOP_LOGGER = {
+	log: () => void 0,
+	error: () => void 0
+};
+/**
+* Predicts the version this repo's next release would be, from commits since the last tagged release -- WITHOUT running semantic-release's own top-level orchestrator. That orchestrator's core (not any plugin) verifies push access to the remote as part of resolving branches before analysis ever runs: genuinely slow, and needing credentials a prediction has no real reason to hold. This calls `analyzeCommits` directly instead -- no network, no registry lookups -- exactly the same hook `@semantic-release/commit-analyzer` exports, supplied by the caller (see `AnalyzeCommits`'s own doc comment for why this package never imports that module itself).
+*
+* Returns `undefined` when there is genuinely no predicted release -- no commits since the last tag, or none of them are release-worthy under `releaseRules` -- the same "nothing to report" case `resolvePredictedIdentity` already treats as valid, not an error. Throws for a genuine setup problem instead of defaulting: `repoRoot` isn't a git repository, or `package.json` has no usable version.
+*
+* @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root, same as `resolveBuildIdentity`).
+* @param releaseRules The commit-analyzer release rules this repo's own commit convention defines.
+* @param analyzeCommits `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- `loadCommitAnalyzer` (`./load-commit-analyzer`) is the tested way to obtain one.
+*/
+async function predictNextVersion(repoRoot, releaseRules, analyzeCommits, options = {}) {
+	const lastVersion = readPackageVersion(repoRoot);
+	const tagName = (options.tagName ?? defaultTagName)(lastVersion);
+	const logger = options.logger ?? NOOP_LOGGER;
+	const commits = readCommitsSince(repoRoot, tagName);
+	if (commits.length === 0) return;
+	const releaseType = await analyzeCommits({ releaseRules: releaseRules.map((rule) => ({ ...rule })) }, {
+		commits,
+		logger,
+		cwd: repoRoot
+	});
+	if (!isReleaseLevel(releaseType)) return;
+	return bumpVersion(lastVersion, releaseType);
+}
+//#endregion
+//#region src/parse-release-rules.ts
+function isUnknownArray(value) {
+	return Array.isArray(value);
+}
+function isReleaseValue(value) {
+	return value === false || isReleaseLevel(value);
+}
+function isReleaseRule(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("release" in value) || !isReleaseValue(value.release)) return false;
+	if ("breaking" in value) return value.breaking === true;
+	if (!("type" in value)) return false;
+	return typeof value.type === "string" && value.type.length > 0;
+}
+/**
+* Validates a JSON array of `@semantic-release/commit-analyzer` release rules supplied on the command line, into the `ReleaseRule[]` `predictNextVersion` takes.
+*
+* The library deliberately hardcodes no rules of its own -- a repo's commit-type-to-release-level convention is real, repo-specific configuration -- so the CLI cannot either, and this is the only route by which it learns them. Every failure names `source` (the flag or file path the JSON came from) so a malformed rule set is traceable back to whichever of the two supplied it.
+*/
+function parseReleaseRules(raw, source) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (cause) {
+		throw new Error(`${source} is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+	if (!isUnknownArray(parsed)) throw new Error(`${source} must be a JSON array of commit-analyzer release rules, e.g. [{"breaking":true,"release":"major"},{"type":"feat","release":"minor"}]`);
+	const rules = [];
+	for (const [index, entry] of parsed.entries()) {
+		if (!isReleaseRule(entry)) throw new Error(`${source}: entry ${String(index)} must be {"type":<string>,"release":"major"|"minor"|"patch"|false} or {"breaking":true,"release":"major"|"minor"|"patch"|false}, got: ${JSON.stringify(entry)}`);
+		rules.push(entry);
+	}
+	return rules;
+}
+//#endregion
+//#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 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 {
+		fullSha: runGit(repoRoot, ["rev-parse", "HEAD"]),
+		shortSha: runGit(repoRoot, [
+			"rev-parse",
+			"--short",
+			"HEAD"
+		]),
+		date: runGit(repoRoot, [
+			"log",
+			"-1",
+			"--format=%aI",
+			"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 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,
+		commit: head.fullSha
+	};
+	return {
+		kind: "commit",
+		version: head.shortSha,
+		url: `https://github.com/${repoSlug}/commit/${head.fullSha}`,
+		date: head.date,
+		commit: head.fullSha
+	};
+}
+//#endregion
+//#region src/resolve-predicted-identity.ts
+/**
+* Upgrades an unreleased build's displayed version to a predicted one (e.g. the version `predictNextVersion` 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 result is `kind: 'predicted'` with `version` set to that predicted label -- `url`/`date`/`commit` are copied verbatim from `build`, still describing the real commit, never a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged (still a valid `DisplayIdentity`, since every `BuildIdentity` kind is also a `DisplayIdentity` kind).
+*
+* This function does no git or filesystem access of its own: predicting the next version is entirely the caller's job, typically `predictNextVersion` (`./predict-next-version`). 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: "predicted",
+		version: trimmedPrediction,
+		url: build.url,
+		date: build.date,
+		commit: build.commit
+	};
+}
+//#endregion
+//#region src/cli-program.ts
+const VERSION_PLACEHOLDER = "{version}";
+const DEFAULT_TAG_TEMPLATE = `v${VERSION_PLACEHOLDER}`;
+const DEFAULT_ENV_PREFIX = "BUILD_";
+/** `predictNextVersion` narrates through a caller-supplied logger and explicitly warns against routing it to stdout, which carries the machine-readable result. `--verbose` sends it to stderr instead, so a CI step can see why a prediction came out the way it did without contaminating what the next step parses. */
+const STDERR_LOGGER = {
+	log: (...args) => {
+		writeStderr(args);
+	},
+	error: (...args) => {
+		writeStderr(args);
+	}
+};
+function writeStderr(args) {
+	process.stderr.write(`${format(...args)}\n`);
+}
+/**
+* A `{version}` template rather than a function, since a command line cannot carry one: `resolveBuildIdentity` and `predictNextVersion` are both given the same resulting function, keeping "which tag marks a release" one convention across the two calls exactly as the library's own docs advise.
+*/
+function parseTagTemplate(template) {
+	if (!template.includes(VERSION_PLACEHOLDER)) throw new InvalidArgumentError(`--tag-name must contain the ${VERSION_PLACEHOLDER} placeholder, got: ${JSON.stringify(template)}`);
+	return (version) => template.replaceAll(VERSION_PLACEHOLDER, version);
+}
+function parseFormat(value) {
+	if (!isOutputFormat(value)) throw new InvalidArgumentError(`--format must be one of: ${OUTPUT_FORMATS.join(", ")}`);
+	return value;
+}
+function parsePrefix(value) {
+	if (!isEnvPrefix(value)) throw new InvalidArgumentError(`--prefix must be empty or a legal variable-name prefix ([A-Za-z_][A-Za-z0-9_]*), got: ${JSON.stringify(value)}`);
+	return value;
+}
+function parseInlineReleaseRules(value) {
+	try {
+		return parseReleaseRules(value, "--release-rules");
+	} catch (cause) {
+		throw new InvalidArgumentError(cause instanceof Error ? cause.message : String(cause));
+	}
+}
+function readReleaseRulesFile(path) {
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (cause) {
+		throw new Error(`--release-rules-file ${path} could not be read: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+	return parseReleaseRules(raw, `--release-rules-file ${path}`);
+}
+/**
+* The whole CLI as a function of its already-parsed flags: resolves the identity and returns the exact text the command prints, so the wiring between the library's three functions is testable without a subprocess and without capturing stdout.
+*
+* Prediction is gated behind `--predict` rather than inferred: it needs `@semantic-release/commit-analyzer`, an optional peer dependency of this package, and reads the whole commit range since the last tag. Both are real costs a caller that only wants `resolveBuildIdentity`'s answer should not silently pay.
+*/
+async function runBuildIdentity(flags) {
+	if (flags.releaseRules !== void 0 && flags.releaseRulesFile !== void 0) throw new Error("--release-rules and --release-rules-file are alternatives; pass one, not both");
+	const rules = flags.releaseRules ?? (flags.releaseRulesFile === void 0 ? void 0 : readReleaseRulesFile(flags.releaseRulesFile));
+	if (flags.predict === true && rules === void 0) throw new Error("--predict needs this repo's own commit-type release rules: pass --release-rules or --release-rules-file");
+	if (flags.predict !== true && rules !== void 0) throw new Error("--release-rules/--release-rules-file only take effect with --predict, which was not passed");
+	const build = resolveBuildIdentity(flags.root, flags.repo, { tagName: flags.tagName });
+	let predictedVersion;
+	if (rules !== void 0) {
+		const options = {
+			tagName: flags.tagName,
+			...flags.verbose === true ? { logger: STDERR_LOGGER } : {}
+		};
+		predictedVersion = await predictNextVersion(flags.root, rules, await loadCommitAnalyzer(), options);
+	}
+	return formatIdentity(resolvePredictedIdentity(build, predictedVersion), {
+		format: flags.format,
+		prefix: flags.prefix
+	});
+}
+/**
+* Builds the commander program without parsing argv or exiting the process, so the command tree stays testable in isolation. There is no subcommand: the package does exactly one thing, and a subcommand naming it again would be pure ceremony.
+*/
+function createProgram() {
+	const program = new Command("build-identity");
+	program.description("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.");
+	program.version(version);
+	program.requiredOption("--repo <owner/repo>", "GitHub slug used to build the release and commit URLs, e.g. exadev/build-identity");
+	program.addOption(new Option("--root <directory>", "git working tree to inspect; must contain package.json at its root").default(process.cwd(), "the current working directory"));
+	program.addOption(new Option("--tag-name <template>", `tag name marking a release, with ${VERSION_PLACEHOLDER} standing in for the version`).argParser(parseTagTemplate).default(defaultTagName, DEFAULT_TAG_TEMPLATE));
+	program.option("--predict", "also predict the version this commit's next release would be, and show that instead of a bare commit hash when there is no release tag on HEAD");
+	program.option("--release-rules <json>", "commit-analyzer release rules for --predict, as a JSON array", parseInlineReleaseRules);
+	program.option("--release-rules-file <path>", "file holding the same JSON array as --release-rules, for a rule set too awkward to quote inline");
+	program.option("--format <format>", `output format: ${OUTPUT_FORMATS.join(" or ")}`, parseFormat, "json");
+	program.option("--prefix <prefix>", "prepended to each variable name in --format env", parsePrefix, DEFAULT_ENV_PREFIX);
+	program.option("--verbose", "send commit-analyzer's own per-commit narration to stderr");
+	program.action(async (flags) => {
+		process.stdout.write(`${await runBuildIdentity(flags)}\n`);
+	});
+	return program;
+}
+//#endregion
+//#region src/cli.ts
+createProgram().parseAsync(process.argv).catch((cause) => {
+	process.stderr.write(`build-identity: ${cause instanceof Error ? cause.stack ?? cause.message : String(cause)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/dist/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_child_process = require("node:child_process");
 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, {
@@ -41,8 +41,8 @@ function tagPointsAtHead(repoRoot, tagName) {
 	]).split("\n").map((line) => line.trim()).includes(tagName);
 }
 //#endregion
-//#region src/resolve-build-identity.ts
-const REPO_SLUG_PATTERN = /^[^/\s]+\/[^/\s]+$/;
+//#region src/package-version.ts
+/** Turns a version into the tag name expected to mark its release -- the shared default (and shared option shape) both `resolveBuildIdentity` and `predictNextVersion` accept, so a repo that tags differently only has to say so once per call site, not maintain two independent conventions. */
 function defaultTagName(version) {
 	return `v${version}`;
 }
@@ -51,6 +51,7 @@ function isPackageJsonWithVersion(value) {
 	if (!("version" in value)) return false;
 	return typeof value.version === "string" && value.version.length > 0;
 }
+/** The single semantic-release-managed version, read from `package.json` at `repoRoot`'s root -- shared by `resolveBuildIdentity` (what this build's version is, if released) and `predictNextVersion` (the version to diff commits since). Throws rather than defaulting, matching this package's own "no sensible placeholder identity" stance. */
 function readPackageVersion(repoRoot) {
 	const packageJsonPath = (0, node_path.join)(repoRoot, "package.json");
 	const raw = (0, node_fs.readFileSync)(packageJsonPath, "utf8");
@@ -58,6 +59,9 @@ function readPackageVersion(repoRoot) {
 	if (!isPackageJsonWithVersion(parsed)) throw new Error(`${packageJsonPath} must contain a non-empty string "version" field`);
 	return parsed.version;
 }
+//#endregion
+//#region src/resolve-build-identity.ts
+const REPO_SLUG_PATTERN = /^[^/\s]+\/[^/\s]+$/;
 function assertRepoSlug(repoSlug) {
 	if (!REPO_SLUG_PATTERN.test(repoSlug)) throw new Error(`repoSlug must be a GitHub "owner/repo" slug, got: ${JSON.stringify(repoSlug)}`);
 }
@@ -92,25 +96,113 @@ function resolveBuildIdentity(repoRoot, repoSlug, options = {}) {
 //#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.
+* Upgrades an unreleased build's displayed version to a predicted one (e.g. the version `predictNextVersion` 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.
+* 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 result is `kind: 'predicted'` with `version` set to that predicted label -- `url`/`date`/`commit` are copied verbatim from `build`, still describing the real commit, never a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged (still a valid `DisplayIdentity`, since every `BuildIdentity` kind is also a `DisplayIdentity` kind).
 *
-* 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.
+* This function does no git or filesystem access of its own: predicting the next version is entirely the caller's job, typically `predictNextVersion` (`./predict-next-version`). 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",
+		kind: "predicted",
 		version: trimmedPrediction,
 		url: build.url,
 		date: build.date,
-		commit: build.commit,
-		predicted: true
+		commit: build.commit
 	};
 }
 //#endregion
+//#region src/predict-next-version.ts
+const GIT_FORMAT = "%x00%H%x00%B";
+const FIELD_SEP = "\0";
+/**
+* Pure parsing of `git log --format=%x00%H%x00%B` output -- split out so it's testable against a raw string fixture with no real git process. NUL is git's own pretty-format escape for a real NUL byte, the one byte git guarantees can never appear inside a commit hash or message (git refuses to store one), making it the only delimiter genuinely safe against arbitrary commit content. Each record is `<hash><NUL><message>`, with a leading NUL on the whole format string, so splitting the entire raw output on NUL and dropping the resulting leading empty token leaves an exact (hash, message) pairing for every commit. Git appends its own trailing newline per record (tformat behaviour); trim() absorbs it the same way it absorbs genuine trailing blank lines in a real commit body.
+*/
+function parseGitLogOutput(raw) {
+	const tokens = raw.split(FIELD_SEP);
+	tokens.shift();
+	const commits = [];
+	for (let index = 0; index < tokens.length; index += 2) commits.push({
+		hash: tokens[index] ?? "",
+		message: (tokens[index + 1] ?? "").trim()
+	});
+	return commits;
+}
+function readCommitsSince(repoRoot, sinceTag) {
+	return parseGitLogOutput((0, node_child_process.execFileSync)("git", [
+		"log",
+		`${sinceTag}..HEAD`,
+		`--format=${GIT_FORMAT}`
+	], {
+		cwd: repoRoot,
+		encoding: "utf-8"
+	}));
+}
+function isReleaseLevel(value) {
+	return value === "major" || value === "minor" || value === "patch";
+}
+/** A trivial major.minor.patch increment -- every version this package works with is a plain X.Y.Z, never a prerelease or build-metadata identifier (see `resolveBuildIdentity`'s own tag convention), so there is no broader semver grammar here worth delegating to a library for. */
+function bumpVersion(version, releaseType) {
+	const [major = 0, minor = 0, patch = 0] = version.split(".").map(Number);
+	if (releaseType === "major") return `${String(major + 1)}.0.0`;
+	if (releaseType === "minor") return `${String(major)}.${String(minor + 1)}.0`;
+	return `${String(major)}.${String(minor)}.${String(patch + 1)}`;
+}
+const NOOP_LOGGER = {
+	log: () => void 0,
+	error: () => void 0
+};
+/**
+* Predicts the version this repo's next release would be, from commits since the last tagged release -- WITHOUT running semantic-release's own top-level orchestrator. That orchestrator's core (not any plugin) verifies push access to the remote as part of resolving branches before analysis ever runs: genuinely slow, and needing credentials a prediction has no real reason to hold. This calls `analyzeCommits` directly instead -- no network, no registry lookups -- exactly the same hook `@semantic-release/commit-analyzer` exports, supplied by the caller (see `AnalyzeCommits`'s own doc comment for why this package never imports that module itself).
+*
+* Returns `undefined` when there is genuinely no predicted release -- no commits since the last tag, or none of them are release-worthy under `releaseRules` -- the same "nothing to report" case `resolvePredictedIdentity` already treats as valid, not an error. Throws for a genuine setup problem instead of defaulting: `repoRoot` isn't a git repository, or `package.json` has no usable version.
+*
+* @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root, same as `resolveBuildIdentity`).
+* @param releaseRules The commit-analyzer release rules this repo's own commit convention defines.
+* @param analyzeCommits `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- `loadCommitAnalyzer` (`./load-commit-analyzer`) is the tested way to obtain one.
+*/
+async function predictNextVersion(repoRoot, releaseRules, analyzeCommits, options = {}) {
+	const lastVersion = readPackageVersion(repoRoot);
+	const tagName = (options.tagName ?? defaultTagName)(lastVersion);
+	const logger = options.logger ?? NOOP_LOGGER;
+	const commits = readCommitsSince(repoRoot, tagName);
+	if (commits.length === 0) return;
+	const releaseType = await analyzeCommits({ releaseRules: releaseRules.map((rule) => ({ ...rule })) }, {
+		commits,
+		logger,
+		cwd: repoRoot
+	});
+	if (!isReleaseLevel(releaseType)) return;
+	return bumpVersion(lastVersion, releaseType);
+}
+//#endregion
+//#region src/load-commit-analyzer.ts
+const COMMIT_ANALYZER_SPECIFIER = "@semantic-release/commit-analyzer";
+function hasAnalyzeCommits(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("analyzeCommits" in value)) return false;
+	return typeof value.analyzeCommits === "function";
+}
+/**
+* Loads `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- the tested, correct way to obtain the `AnalyzeCommits` implementation `predictNextVersion` (`./predict-next-version`) needs. Split out from `predictNextVersion` itself so that function stays a pure, easily-fakeable function of its own arguments; this is the one place in the package that actually touches the untyped module.
+*
+* `@semantic-release/commit-analyzer` is an optional peer dependency (see this package's own `package.json`): not required to use `resolveBuildIdentity`/`resolvePredictedIdentity`, only to call this function. Throws a clear error, rather than a bare "Cannot find module", when it isn't installed or doesn't export `analyzeCommits` -- a version bump of the real package removing or renaming that export fails loudly here, not silently.
+*/
+async function loadCommitAnalyzer() {
+	let commitAnalyzerModule;
+	try {
+		commitAnalyzerModule = await import(COMMIT_ANALYZER_SPECIFIER);
+	} catch (error) {
+		throw new Error("@semantic-release/commit-analyzer is not installed -- it is an optional peer dependency of @exadev/build-identity, required only for loadCommitAnalyzer/predictNextVersion.", { cause: error });
+	}
+	if (!hasAnalyzeCommits(commitAnalyzerModule)) throw new Error("@semantic-release/commit-analyzer has no analyzeCommits export.");
+	return commitAnalyzerModule.analyzeCommits;
+}
+//#endregion
+exports.loadCommitAnalyzer = loadCommitAnalyzer;
+exports.predictNextVersion = predictNextVersion;
 exports.resolveBuildIdentity = resolveBuildIdentity;
 exports.resolvePredictedIdentity = resolvePredictedIdentity;

package/dist/index.d.cts

@@ -31,6 +31,16 @@ interface ResolveBuildIdentityOptions {
    */
   readonly tagName?: (version: string) => string;
 }
+/**
+ * What a build should actually display -- `BuildIdentity` refined by an optional prediction (`resolvePredictedIdentity`). All three kinds carry the identical field set; only the meaning of `kind`/`version` differs: `'release'` and `'commit'` mean exactly what they do on `BuildIdentity` (a confirmed release always wins outright, unchanged), and `'predicted'` means "not yet released, but a commit-analyzer-style tool predicts this commit will become `version` once it is" -- `url`/`date`/`commit` still describe the real underlying commit, never a release page that doesn't exist yet.
+ */
+interface DisplayIdentity {
+  readonly kind: 'release' | 'predicted' | 'commit';
+  readonly version: string;
+  readonly url: string;
+  readonly date: string;
+  readonly commit: string;
+}
 //#endregion
 //#region src/resolve-build-identity.d.ts
 /**
@@ -45,14 +55,54 @@ declare function resolveBuildIdentity(repoRoot: string, repoSlug: string, option
 //#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.
+ * Upgrades an unreleased build's displayed version to a predicted one (e.g. the version `predictNextVersion` 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.
+ * 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 result is `kind: 'predicted'` with `version` set to that predicted label -- `url`/`date`/`commit` are copied verbatim from `build`, still describing the real commit, never a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged (still a valid `DisplayIdentity`, since every `BuildIdentity` kind is also a `DisplayIdentity` kind).
  *
- * 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.
+ * This function does no git or filesystem access of its own: predicting the next version is entirely the caller's job, typically `predictNextVersion` (`./predict-next-version`). 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;
+declare function resolvePredictedIdentity(build: BuildIdentity, predictedVersion: string | undefined): DisplayIdentity;
+//#endregion
+//#region src/predict-next-version.d.ts
+type ReleaseLevel = 'major' | 'minor' | 'patch';
+/** One @semantic-release/commit-analyzer release rule -- either `{ type, release }` (a conventional-commit type, e.g. `"feat"`) or `{ breaking: true, release }` (any commit whose footer/body declares a breaking change, regardless of type). `release` also accepts `false`, commit-analyzer's own way to say "this type never triggers a release" -- needed to override a broader rule or preset default, distinct from simply omitting the type (which instead falls through to whatever the preset's own default is). This package hardcodes no rules of its own: a repo's commit-type-to-release-level convention is real, repo-specific configuration. */
+type ReleaseRule = {
+  readonly type: string;
+  readonly release: ReleaseLevel | false;
+} | {
+  readonly breaking: true;
+  readonly release: ReleaseLevel | false;
 };
+/**
+ * The shape of `@semantic-release/commit-analyzer`'s own `analyzeCommits` plugin hook -- untyped and undocumented as a standalone export (it exists only because semantic-release's own core loads plugins dynamically), so this package can promise no more about it than "callable with these two arguments, returns a promise." `predictNextVersion` takes an implementation of this type as a parameter, rather than loading `@semantic-release/commit-analyzer` itself, so it stays a pure function of its own arguments -- trivially testable with a fake analyzer, exactly how this file's own tests exercise it. `./load-commit-analyzer`'s `loadCommitAnalyzer` is the tested, correct way to obtain a real one; pass its result straight through when you don't need a different implementation.
+ */
+type AnalyzeCommits = (pluginConfig: unknown, context: unknown) => Promise<unknown>;
+interface PredictNextVersionOptions {
+  /** Matches `resolveBuildIdentity`'s own option of the same name -- pass the same function to both when a repo tags non-default, so "which tag marks the last release" stays one convention rather than two that could drift apart. Defaults to the `v${version}` convention. */
+  tagName?: (version: string) => string;
+  /** Receives @semantic-release/commit-analyzer's own per-commit narration (e.g. "Analyzing commit: ...", "The release type for the commit is minor"). Defaults to discarding it. Pass your own to route it to stderr or a real logger -- never stdout, so a caller parsing a single predicted-version line from this process's own stdout is never at risk of it being contaminated. */
+  logger?: {
+    log: (...args: readonly unknown[]) => void;
+    error: (...args: readonly unknown[]) => void;
+  };
+}
+/**
+ * Predicts the version this repo's next release would be, from commits since the last tagged release -- WITHOUT running semantic-release's own top-level orchestrator. That orchestrator's core (not any plugin) verifies push access to the remote as part of resolving branches before analysis ever runs: genuinely slow, and needing credentials a prediction has no real reason to hold. This calls `analyzeCommits` directly instead -- no network, no registry lookups -- exactly the same hook `@semantic-release/commit-analyzer` exports, supplied by the caller (see `AnalyzeCommits`'s own doc comment for why this package never imports that module itself).
+ *
+ * Returns `undefined` when there is genuinely no predicted release -- no commits since the last tag, or none of them are release-worthy under `releaseRules` -- the same "nothing to report" case `resolvePredictedIdentity` already treats as valid, not an error. Throws for a genuine setup problem instead of defaulting: `repoRoot` isn't a git repository, or `package.json` has no usable version.
+ *
+ * @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root, same as `resolveBuildIdentity`).
+ * @param releaseRules The commit-analyzer release rules this repo's own commit convention defines.
+ * @param analyzeCommits `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- `loadCommitAnalyzer` (`./load-commit-analyzer`) is the tested way to obtain one.
+ */
+declare function predictNextVersion(repoRoot: string, releaseRules: readonly ReleaseRule[], analyzeCommits: AnalyzeCommits, options?: PredictNextVersionOptions): Promise<string | undefined>;
+//#endregion
+//#region src/load-commit-analyzer.d.ts
+/**
+ * Loads `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- the tested, correct way to obtain the `AnalyzeCommits` implementation `predictNextVersion` (`./predict-next-version`) needs. Split out from `predictNextVersion` itself so that function stays a pure, easily-fakeable function of its own arguments; this is the one place in the package that actually touches the untyped module.
+ *
+ * `@semantic-release/commit-analyzer` is an optional peer dependency (see this package's own `package.json`): not required to use `resolveBuildIdentity`/`resolvePredictedIdentity`, only to call this function. Throws a clear error, rather than a bare "Cannot find module", when it isn't installed or doesn't export `analyzeCommits` -- a version bump of the real package removing or renaming that export fails loudly here, not silently.
+ */
+declare function loadCommitAnalyzer(): Promise<AnalyzeCommits>;
 //#endregion
-export { type BuildIdentity, type ResolveBuildIdentityOptions, resolveBuildIdentity, resolvePredictedIdentity };
+export { type AnalyzeCommits, type BuildIdentity, type DisplayIdentity, type PredictNextVersionOptions, type ReleaseLevel, type ReleaseRule, type ResolveBuildIdentityOptions, loadCommitAnalyzer, predictNextVersion, resolveBuildIdentity, resolvePredictedIdentity };

package/dist/index.d.ts

@@ -31,6 +31,16 @@ interface ResolveBuildIdentityOptions {
    */
   readonly tagName?: (version: string) => string;
 }
+/**
+ * What a build should actually display -- `BuildIdentity` refined by an optional prediction (`resolvePredictedIdentity`). All three kinds carry the identical field set; only the meaning of `kind`/`version` differs: `'release'` and `'commit'` mean exactly what they do on `BuildIdentity` (a confirmed release always wins outright, unchanged), and `'predicted'` means "not yet released, but a commit-analyzer-style tool predicts this commit will become `version` once it is" -- `url`/`date`/`commit` still describe the real underlying commit, never a release page that doesn't exist yet.
+ */
+interface DisplayIdentity {
+  readonly kind: 'release' | 'predicted' | 'commit';
+  readonly version: string;
+  readonly url: string;
+  readonly date: string;
+  readonly commit: string;
+}
 //#endregion
 //#region src/resolve-build-identity.d.ts
 /**
@@ -45,14 +55,54 @@ declare function resolveBuildIdentity(repoRoot: string, repoSlug: string, option
 //#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.
+ * Upgrades an unreleased build's displayed version to a predicted one (e.g. the version `predictNextVersion` 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.
+ * 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 result is `kind: 'predicted'` with `version` set to that predicted label -- `url`/`date`/`commit` are copied verbatim from `build`, still describing the real commit, never a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged (still a valid `DisplayIdentity`, since every `BuildIdentity` kind is also a `DisplayIdentity` kind).
  *
- * 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.
+ * This function does no git or filesystem access of its own: predicting the next version is entirely the caller's job, typically `predictNextVersion` (`./predict-next-version`). 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;
+declare function resolvePredictedIdentity(build: BuildIdentity, predictedVersion: string | undefined): DisplayIdentity;
+//#endregion
+//#region src/predict-next-version.d.ts
+type ReleaseLevel = 'major' | 'minor' | 'patch';
+/** One @semantic-release/commit-analyzer release rule -- either `{ type, release }` (a conventional-commit type, e.g. `"feat"`) or `{ breaking: true, release }` (any commit whose footer/body declares a breaking change, regardless of type). `release` also accepts `false`, commit-analyzer's own way to say "this type never triggers a release" -- needed to override a broader rule or preset default, distinct from simply omitting the type (which instead falls through to whatever the preset's own default is). This package hardcodes no rules of its own: a repo's commit-type-to-release-level convention is real, repo-specific configuration. */
+type ReleaseRule = {
+  readonly type: string;
+  readonly release: ReleaseLevel | false;
+} | {
+  readonly breaking: true;
+  readonly release: ReleaseLevel | false;
 };
+/**
+ * The shape of `@semantic-release/commit-analyzer`'s own `analyzeCommits` plugin hook -- untyped and undocumented as a standalone export (it exists only because semantic-release's own core loads plugins dynamically), so this package can promise no more about it than "callable with these two arguments, returns a promise." `predictNextVersion` takes an implementation of this type as a parameter, rather than loading `@semantic-release/commit-analyzer` itself, so it stays a pure function of its own arguments -- trivially testable with a fake analyzer, exactly how this file's own tests exercise it. `./load-commit-analyzer`'s `loadCommitAnalyzer` is the tested, correct way to obtain a real one; pass its result straight through when you don't need a different implementation.
+ */
+type AnalyzeCommits = (pluginConfig: unknown, context: unknown) => Promise<unknown>;
+interface PredictNextVersionOptions {
+  /** Matches `resolveBuildIdentity`'s own option of the same name -- pass the same function to both when a repo tags non-default, so "which tag marks the last release" stays one convention rather than two that could drift apart. Defaults to the `v${version}` convention. */
+  tagName?: (version: string) => string;
+  /** Receives @semantic-release/commit-analyzer's own per-commit narration (e.g. "Analyzing commit: ...", "The release type for the commit is minor"). Defaults to discarding it. Pass your own to route it to stderr or a real logger -- never stdout, so a caller parsing a single predicted-version line from this process's own stdout is never at risk of it being contaminated. */
+  logger?: {
+    log: (...args: readonly unknown[]) => void;
+    error: (...args: readonly unknown[]) => void;
+  };
+}
+/**
+ * Predicts the version this repo's next release would be, from commits since the last tagged release -- WITHOUT running semantic-release's own top-level orchestrator. That orchestrator's core (not any plugin) verifies push access to the remote as part of resolving branches before analysis ever runs: genuinely slow, and needing credentials a prediction has no real reason to hold. This calls `analyzeCommits` directly instead -- no network, no registry lookups -- exactly the same hook `@semantic-release/commit-analyzer` exports, supplied by the caller (see `AnalyzeCommits`'s own doc comment for why this package never imports that module itself).
+ *
+ * Returns `undefined` when there is genuinely no predicted release -- no commits since the last tag, or none of them are release-worthy under `releaseRules` -- the same "nothing to report" case `resolvePredictedIdentity` already treats as valid, not an error. Throws for a genuine setup problem instead of defaulting: `repoRoot` isn't a git repository, or `package.json` has no usable version.
+ *
+ * @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root, same as `resolveBuildIdentity`).
+ * @param releaseRules The commit-analyzer release rules this repo's own commit convention defines.
+ * @param analyzeCommits `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- `loadCommitAnalyzer` (`./load-commit-analyzer`) is the tested way to obtain one.
+ */
+declare function predictNextVersion(repoRoot: string, releaseRules: readonly ReleaseRule[], analyzeCommits: AnalyzeCommits, options?: PredictNextVersionOptions): Promise<string | undefined>;
+//#endregion
+//#region src/load-commit-analyzer.d.ts
+/**
+ * Loads `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- the tested, correct way to obtain the `AnalyzeCommits` implementation `predictNextVersion` (`./predict-next-version`) needs. Split out from `predictNextVersion` itself so that function stays a pure, easily-fakeable function of its own arguments; this is the one place in the package that actually touches the untyped module.
+ *
+ * `@semantic-release/commit-analyzer` is an optional peer dependency (see this package's own `package.json`): not required to use `resolveBuildIdentity`/`resolvePredictedIdentity`, only to call this function. Throws a clear error, rather than a bare "Cannot find module", when it isn't installed or doesn't export `analyzeCommits` -- a version bump of the real package removing or renaming that export fails loudly here, not silently.
+ */
+declare function loadCommitAnalyzer(): Promise<AnalyzeCommits>;
 //#endregion
-export { type BuildIdentity, type ResolveBuildIdentityOptions, resolveBuildIdentity, resolvePredictedIdentity };
+export { type AnalyzeCommits, type BuildIdentity, type DisplayIdentity, type PredictNextVersionOptions, type ReleaseLevel, type ReleaseRule, type ResolveBuildIdentityOptions, loadCommitAnalyzer, predictNextVersion, resolveBuildIdentity, resolvePredictedIdentity };

package/dist/index.js

@@ -1,6 +1,6 @@
+import { execFileSync } from "node:child_process";
 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, {
@@ -40,8 +40,8 @@ function tagPointsAtHead(repoRoot, tagName) {
 	]).split("\n").map((line) => line.trim()).includes(tagName);
 }
 //#endregion
-//#region src/resolve-build-identity.ts
-const REPO_SLUG_PATTERN = /^[^/\s]+\/[^/\s]+$/;
+//#region src/package-version.ts
+/** Turns a version into the tag name expected to mark its release -- the shared default (and shared option shape) both `resolveBuildIdentity` and `predictNextVersion` accept, so a repo that tags differently only has to say so once per call site, not maintain two independent conventions. */
 function defaultTagName(version) {
 	return `v${version}`;
 }
@@ -50,6 +50,7 @@ function isPackageJsonWithVersion(value) {
 	if (!("version" in value)) return false;
 	return typeof value.version === "string" && value.version.length > 0;
 }
+/** The single semantic-release-managed version, read from `package.json` at `repoRoot`'s root -- shared by `resolveBuildIdentity` (what this build's version is, if released) and `predictNextVersion` (the version to diff commits since). Throws rather than defaulting, matching this package's own "no sensible placeholder identity" stance. */
 function readPackageVersion(repoRoot) {
 	const packageJsonPath = join(repoRoot, "package.json");
 	const raw = readFileSync(packageJsonPath, "utf8");
@@ -57,6 +58,9 @@ function readPackageVersion(repoRoot) {
 	if (!isPackageJsonWithVersion(parsed)) throw new Error(`${packageJsonPath} must contain a non-empty string "version" field`);
 	return parsed.version;
 }
+//#endregion
+//#region src/resolve-build-identity.ts
+const REPO_SLUG_PATTERN = /^[^/\s]+\/[^/\s]+$/;
 function assertRepoSlug(repoSlug) {
 	if (!REPO_SLUG_PATTERN.test(repoSlug)) throw new Error(`repoSlug must be a GitHub "owner/repo" slug, got: ${JSON.stringify(repoSlug)}`);
 }
@@ -91,24 +95,110 @@ function resolveBuildIdentity(repoRoot, repoSlug, options = {}) {
 //#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.
+* Upgrades an unreleased build's displayed version to a predicted one (e.g. the version `predictNextVersion` 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.
+* 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 result is `kind: 'predicted'` with `version` set to that predicted label -- `url`/`date`/`commit` are copied verbatim from `build`, still describing the real commit, never a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged (still a valid `DisplayIdentity`, since every `BuildIdentity` kind is also a `DisplayIdentity` kind).
 *
-* 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.
+* This function does no git or filesystem access of its own: predicting the next version is entirely the caller's job, typically `predictNextVersion` (`./predict-next-version`). 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",
+		kind: "predicted",
 		version: trimmedPrediction,
 		url: build.url,
 		date: build.date,
-		commit: build.commit,
-		predicted: true
+		commit: build.commit
 	};
 }
 //#endregion
-export { resolveBuildIdentity, resolvePredictedIdentity };
+//#region src/predict-next-version.ts
+const GIT_FORMAT = "%x00%H%x00%B";
+const FIELD_SEP = "\0";
+/**
+* Pure parsing of `git log --format=%x00%H%x00%B` output -- split out so it's testable against a raw string fixture with no real git process. NUL is git's own pretty-format escape for a real NUL byte, the one byte git guarantees can never appear inside a commit hash or message (git refuses to store one), making it the only delimiter genuinely safe against arbitrary commit content. Each record is `<hash><NUL><message>`, with a leading NUL on the whole format string, so splitting the entire raw output on NUL and dropping the resulting leading empty token leaves an exact (hash, message) pairing for every commit. Git appends its own trailing newline per record (tformat behaviour); trim() absorbs it the same way it absorbs genuine trailing blank lines in a real commit body.
+*/
+function parseGitLogOutput(raw) {
+	const tokens = raw.split(FIELD_SEP);
+	tokens.shift();
+	const commits = [];
+	for (let index = 0; index < tokens.length; index += 2) commits.push({
+		hash: tokens[index] ?? "",
+		message: (tokens[index + 1] ?? "").trim()
+	});
+	return commits;
+}
+function readCommitsSince(repoRoot, sinceTag) {
+	return parseGitLogOutput(execFileSync("git", [
+		"log",
+		`${sinceTag}..HEAD`,
+		`--format=${GIT_FORMAT}`
+	], {
+		cwd: repoRoot,
+		encoding: "utf-8"
+	}));
+}
+function isReleaseLevel(value) {
+	return value === "major" || value === "minor" || value === "patch";
+}
+/** A trivial major.minor.patch increment -- every version this package works with is a plain X.Y.Z, never a prerelease or build-metadata identifier (see `resolveBuildIdentity`'s own tag convention), so there is no broader semver grammar here worth delegating to a library for. */
+function bumpVersion(version, releaseType) {
+	const [major = 0, minor = 0, patch = 0] = version.split(".").map(Number);
+	if (releaseType === "major") return `${String(major + 1)}.0.0`;
+	if (releaseType === "minor") return `${String(major)}.${String(minor + 1)}.0`;
+	return `${String(major)}.${String(minor)}.${String(patch + 1)}`;
+}
+const NOOP_LOGGER = {
+	log: () => void 0,
+	error: () => void 0
+};
+/**
+* Predicts the version this repo's next release would be, from commits since the last tagged release -- WITHOUT running semantic-release's own top-level orchestrator. That orchestrator's core (not any plugin) verifies push access to the remote as part of resolving branches before analysis ever runs: genuinely slow, and needing credentials a prediction has no real reason to hold. This calls `analyzeCommits` directly instead -- no network, no registry lookups -- exactly the same hook `@semantic-release/commit-analyzer` exports, supplied by the caller (see `AnalyzeCommits`'s own doc comment for why this package never imports that module itself).
+*
+* Returns `undefined` when there is genuinely no predicted release -- no commits since the last tag, or none of them are release-worthy under `releaseRules` -- the same "nothing to report" case `resolvePredictedIdentity` already treats as valid, not an error. Throws for a genuine setup problem instead of defaulting: `repoRoot` isn't a git repository, or `package.json` has no usable version.
+*
+* @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root, same as `resolveBuildIdentity`).
+* @param releaseRules The commit-analyzer release rules this repo's own commit convention defines.
+* @param analyzeCommits `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- `loadCommitAnalyzer` (`./load-commit-analyzer`) is the tested way to obtain one.
+*/
+async function predictNextVersion(repoRoot, releaseRules, analyzeCommits, options = {}) {
+	const lastVersion = readPackageVersion(repoRoot);
+	const tagName = (options.tagName ?? defaultTagName)(lastVersion);
+	const logger = options.logger ?? NOOP_LOGGER;
+	const commits = readCommitsSince(repoRoot, tagName);
+	if (commits.length === 0) return;
+	const releaseType = await analyzeCommits({ releaseRules: releaseRules.map((rule) => ({ ...rule })) }, {
+		commits,
+		logger,
+		cwd: repoRoot
+	});
+	if (!isReleaseLevel(releaseType)) return;
+	return bumpVersion(lastVersion, releaseType);
+}
+//#endregion
+//#region src/load-commit-analyzer.ts
+const COMMIT_ANALYZER_SPECIFIER = "@semantic-release/commit-analyzer";
+function hasAnalyzeCommits(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("analyzeCommits" in value)) return false;
+	return typeof value.analyzeCommits === "function";
+}
+/**
+* Loads `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- the tested, correct way to obtain the `AnalyzeCommits` implementation `predictNextVersion` (`./predict-next-version`) needs. Split out from `predictNextVersion` itself so that function stays a pure, easily-fakeable function of its own arguments; this is the one place in the package that actually touches the untyped module.
+*
+* `@semantic-release/commit-analyzer` is an optional peer dependency (see this package's own `package.json`): not required to use `resolveBuildIdentity`/`resolvePredictedIdentity`, only to call this function. Throws a clear error, rather than a bare "Cannot find module", when it isn't installed or doesn't export `analyzeCommits` -- a version bump of the real package removing or renaming that export fails loudly here, not silently.
+*/
+async function loadCommitAnalyzer() {
+	let commitAnalyzerModule;
+	try {
+		commitAnalyzerModule = await import(COMMIT_ANALYZER_SPECIFIER);
+	} catch (error) {
+		throw new Error("@semantic-release/commit-analyzer is not installed -- it is an optional peer dependency of @exadev/build-identity, required only for loadCommitAnalyzer/predictNextVersion.", { cause: error });
+	}
+	if (!hasAnalyzeCommits(commitAnalyzerModule)) throw new Error("@semantic-release/commit-analyzer has no analyzeCommits export.");
+	return commitAnalyzerModule.analyzeCommits;
+}
+//#endregion
+export { loadCommitAnalyzer, predictNextVersion, resolveBuildIdentity, resolvePredictedIdentity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exadev/build-identity",
-  "version": "1.1.0",
+  "version": "2.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,
@@ -12,6 +12,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "bin": {
+    "build-identity": "./dist/cli.js"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -33,18 +36,28 @@
     "version",
     "git",
     "release",
-    "commit"
+    "commit",
+    "cli"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ExaDev/build-identity.git"
   },
+  "peerDependencies": {
+    "@semantic-release/commit-analyzer": "^13.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@semantic-release/commit-analyzer": {
+      "optional": true
+    }
+  },
   "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/commit-analyzer": "13.0.1",
     "@semantic-release/git": "11.0.1",
     "@types/node": "24.13.3",
     "@vitest/coverage-v8": "4.1.10",
@@ -71,5 +84,8 @@
     "prepublishOnly": "pnpm run lint && pnpm run typecheck && pnpm run test && tsdown && publint && attw --pack",
     "prepare": "husky",
     "release": "semantic-release"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
   }
 }