@exadev/build-identity 2.1.0 → 2.2.1

package/README.md

@@ -118,6 +118,23 @@ const predictedVersion = await predictNextVersion(process.cwd(), releaseRules, a
 const identity = resolvePredictedIdentity(build, predictedVersion);
 ```
 
+## `readPackageVersion(repoRoot)`
+
+```ts
+function readPackageVersion(repoRoot: string): string;
+```
+
+The plain `"version"` field from `package.json` at `repoRoot`, read unconditionally and with no git access at all. This is deliberately not the same thing as `resolveBuildIdentity(...).version`, which is a build *identity* -- the released version only when a tag genuinely points at HEAD, and a short commit hash otherwise. Reach for this one when you want the last released semantic version regardless of whether this checkout happens to be sitting on its tag: an OpenAPI document's `info.version`, a user agent string, anything wanting a stable semver rather than an honest answer about what is deployed.
+
+Throws rather than defaulting when `package.json` is missing or its `"version"` is absent, non-string, or empty -- the same stance every other export in this package takes. `defaultTagName` (`v${version}`) is the shared convention `resolveBuildIdentity` and `predictNextVersion` both apply to this value.
+
+```ts
+import { readPackageVersion, resolveBuildIdentity } from '@exadev/build-identity';
+
+const appVersion = readPackageVersion(process.cwd()); // "1.4.0", tagged or not
+const build = resolveBuildIdentity(process.cwd(), 'exadev/example'); // "1.4.0" or "a1b2c3d"
+```
+
 ## `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.

package/dist/cli.js

@@ -5,7 +5,7 @@ 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";
+var version = "2.2.1";
 //#endregion
 //#region src/format-identity.ts
 const OUTPUT_FORMATS = ["json", "env"];
@@ -128,10 +128,9 @@ const NOOP_LOGGER = {
 * 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.
+* @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);
@@ -231,9 +230,8 @@ function assertRepoSlug(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.
+* @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);

package/dist/index.cjs

@@ -69,9 +69,8 @@ function assertRepoSlug(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.
+* @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);
@@ -159,10 +158,9 @@ const NOOP_LOGGER = {
 * 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.
+* @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);
@@ -204,5 +202,6 @@ async function loadCommitAnalyzer() {
 //#endregion
 exports.loadCommitAnalyzer = loadCommitAnalyzer;
 exports.predictNextVersion = predictNextVersion;
+exports.readPackageVersion = readPackageVersion;
 exports.resolveBuildIdentity = resolveBuildIdentity;
 exports.resolvePredictedIdentity = resolvePredictedIdentity;

package/dist/index.d.cts

@@ -27,7 +27,7 @@ type BuildIdentity = {
 };
 interface ResolveBuildIdentityOptions {
   /**
-   * Turns the version read from `package.json` into the git tag name that is expected to mark its release. Defaults to a `v` prefix (`"1.4.0"` -> `"v1.4.0"`), the convention this package's own release tooling and GitHub's own release UI both use -- override it for a repo that tags releases differently (a bare version, a package-scoped prefix in a monorepo, and so on).
+   * Turns the version read from `package.json` into the git tag name that is expected to mark its release. Defaults to a `v` prefix (`"1.4.0"` -\> `"v1.4.0"`), the convention this package's own release tooling and GitHub's own release UI both use -- override it for a repo that tags releases differently (a bare version, a package-scoped prefix in a monorepo, and so on).
    */
   readonly tagName?: (version: string) => string;
 }
@@ -47,9 +47,8 @@ interface DisplayIdentity {
  * 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.
+ * @param repoRoot - Path to the git working tree to inspect (must contain `package.json` at its root).
+ * @param repoSlug - The GitHub `owner/repo` slug used to build both release and commit URLs.
  */
 declare function resolveBuildIdentity(repoRoot: string, repoSlug: string, options?: ResolveBuildIdentityOptions): BuildIdentity;
 //#endregion
@@ -65,7 +64,7 @@ declare function resolvePredictedIdentity(build: BuildIdentity, predictedVersion
 //#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. */
+/** 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;
@@ -80,7 +79,7 @@ type AnalyzeCommits = (pluginConfig: unknown, context: unknown) => Promise<unkno
 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. */
+  /** 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;
@@ -90,10 +89,9 @@ interface PredictNextVersionOptions {
  * 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.
+ * @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
@@ -105,4 +103,8 @@ declare function predictNextVersion(repoRoot: string, releaseRules: readonly Rel
  */
 declare function loadCommitAnalyzer(): Promise<AnalyzeCommits>;
 //#endregion
-export { type AnalyzeCommits, type BuildIdentity, type DisplayIdentity, type PredictNextVersionOptions, type ReleaseLevel, type ReleaseRule, type ResolveBuildIdentityOptions, loadCommitAnalyzer, predictNextVersion, resolveBuildIdentity, resolvePredictedIdentity };
+//#region src/package-version.d.ts
+/** 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. */
+declare function readPackageVersion(repoRoot: string): string;
+//#endregion
+export { type AnalyzeCommits, type BuildIdentity, type DisplayIdentity, type PredictNextVersionOptions, type ReleaseLevel, type ReleaseRule, type ResolveBuildIdentityOptions, loadCommitAnalyzer, predictNextVersion, readPackageVersion, resolveBuildIdentity, resolvePredictedIdentity };

package/dist/index.d.ts

@@ -27,7 +27,7 @@ type BuildIdentity = {
 };
 interface ResolveBuildIdentityOptions {
   /**
-   * Turns the version read from `package.json` into the git tag name that is expected to mark its release. Defaults to a `v` prefix (`"1.4.0"` -> `"v1.4.0"`), the convention this package's own release tooling and GitHub's own release UI both use -- override it for a repo that tags releases differently (a bare version, a package-scoped prefix in a monorepo, and so on).
+   * Turns the version read from `package.json` into the git tag name that is expected to mark its release. Defaults to a `v` prefix (`"1.4.0"` -\> `"v1.4.0"`), the convention this package's own release tooling and GitHub's own release UI both use -- override it for a repo that tags releases differently (a bare version, a package-scoped prefix in a monorepo, and so on).
    */
   readonly tagName?: (version: string) => string;
 }
@@ -47,9 +47,8 @@ interface DisplayIdentity {
  * 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.
+ * @param repoRoot - Path to the git working tree to inspect (must contain `package.json` at its root).
+ * @param repoSlug - The GitHub `owner/repo` slug used to build both release and commit URLs.
  */
 declare function resolveBuildIdentity(repoRoot: string, repoSlug: string, options?: ResolveBuildIdentityOptions): BuildIdentity;
 //#endregion
@@ -65,7 +64,7 @@ declare function resolvePredictedIdentity(build: BuildIdentity, predictedVersion
 //#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. */
+/** 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;
@@ -80,7 +79,7 @@ type AnalyzeCommits = (pluginConfig: unknown, context: unknown) => Promise<unkno
 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. */
+  /** 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;
@@ -90,10 +89,9 @@ interface PredictNextVersionOptions {
  * 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.
+ * @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
@@ -105,4 +103,8 @@ declare function predictNextVersion(repoRoot: string, releaseRules: readonly Rel
  */
 declare function loadCommitAnalyzer(): Promise<AnalyzeCommits>;
 //#endregion
-export { type AnalyzeCommits, type BuildIdentity, type DisplayIdentity, type PredictNextVersionOptions, type ReleaseLevel, type ReleaseRule, type ResolveBuildIdentityOptions, loadCommitAnalyzer, predictNextVersion, resolveBuildIdentity, resolvePredictedIdentity };
+//#region src/package-version.d.ts
+/** 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. */
+declare function readPackageVersion(repoRoot: string): string;
+//#endregion
+export { type AnalyzeCommits, type BuildIdentity, type DisplayIdentity, type PredictNextVersionOptions, type ReleaseLevel, type ReleaseRule, type ResolveBuildIdentityOptions, loadCommitAnalyzer, predictNextVersion, readPackageVersion, resolveBuildIdentity, resolvePredictedIdentity };

package/dist/index.js

@@ -68,9 +68,8 @@ function assertRepoSlug(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.
+* @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);
@@ -158,10 +157,9 @@ const NOOP_LOGGER = {
 * 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.
+* @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);
@@ -201,4 +199,4 @@ async function loadCommitAnalyzer() {
 	return commitAnalyzerModule.analyzeCommits;
 }
 //#endregion
-export { loadCommitAnalyzer, predictNextVersion, resolveBuildIdentity, resolvePredictedIdentity };
+export { loadCommitAnalyzer, predictNextVersion, readPackageVersion, resolveBuildIdentity, resolvePredictedIdentity };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@exadev/build-identity",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Resolve a build's true identity (a real release tag, or the commit it was built from) from git state, with an optional predicted-version display layer",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
-  "packageManager": "pnpm@11.6.0",
+  "packageManager": "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
   "engines": {
     "node": ">=20"
   },
@@ -55,7 +55,7 @@
     "@arethetypeswrong/cli": "0.18.5",
     "@commitlint/cli": "21.2.1",
     "@commitlint/config-conventional": "21.2.0",
-    "@exadev/eslint-config": "^2.10.4",
+    "@exadev/eslint-config": "2.12.1",
     "@semantic-release/changelog": "7.0.0",
     "@semantic-release/commit-analyzer": "13.0.1",
     "@semantic-release/git": "11.0.1",