@exadev/build-identity 1.1.0 → 2.0.0

package/README.md

@@ -50,22 +50,69 @@ 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);
 ```
 
@@ -111,7 +158,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/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.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,
@@ -39,12 +39,21 @@
     "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",