/**
 * A git commit with its metadata.
 */
interface GitCommit {
    /** Full commit hash (40 characters) */
    readonly hash: string;
    /** Abbreviated commit hash (typically 7 characters) */
    readonly shortHash: string;
    /** Commit author name */
    readonly authorName: string;
    /** Commit author email */
    readonly authorEmail: string;
    /** Author date (ISO 8601 format) */
    readonly authorDate: string;
    /** Committer name */
    readonly committerName: string;
    /** Committer email */
    readonly committerEmail: string;
    /** Commit date (ISO 8601 format) */
    readonly commitDate: string;
    /** Commit subject (first line of message) */
    readonly subject: string;
    /** Full commit body (excludes subject) */
    readonly body: string;
    /** Full commit message (subject + body) */
    readonly message: string;
    /** Parent commit hashes */
    readonly parents: readonly string[];
    /** Associated refs (branches, tags, etc.) */
    readonly refs: readonly string[];
}
/**
 * Options for creating a git commit model.
 */
interface CreateGitCommitOptions {
    /** Full commit hash */
    readonly hash: string;
    /** Commit author name */
    readonly authorName: string;
    /** Commit author email */
    readonly authorEmail: string;
    /** Author date (ISO 8601 format) */
    readonly authorDate: string;
    /** Commit subject (first line of message) */
    readonly subject: string;
    /** Committer name (defaults to author) */
    readonly committerName?: string;
    /** Committer email (defaults to author) */
    readonly committerEmail?: string;
    /** Commit date (defaults to author date) */
    readonly commitDate?: string;
    /** Full commit body (defaults to empty string) */
    readonly body?: string;
    /** Parent commit hashes (defaults to empty array) */
    readonly parents?: readonly string[];
    /** Associated refs (defaults to empty array) */
    readonly refs?: readonly string[];
}
/**
 * Creates a git commit model.
 *
 * @param options - Commit creation options
 * @returns A new GitCommit object
 *
 * @example Create a git commit model
 * const commit = createGitCommit({
 *   hash: 'abc123...',
 *   authorName: 'John Doe',
 *   authorEmail: 'john@example.com',
 *   authorDate: '2026-03-12T10:00:00Z',
 *   subject: 'feat: add new feature',
 * })
 */
declare function createGitCommit(options: CreateGitCommitOptions): GitCommit;
/**
 * Gets a short hash (7 characters) from a full commit hash.
 *
 * @param hash - Full commit hash
 * @returns Short hash (7 characters)
 *
 * @example Get short hash from full commit hash
 * ```typescript
 * getShortHash('abc123def456789') // => 'abc123d'
 * ```
 */
declare function getShortHash(hash: string): string;
/**
 * Checks if two commits are the same based on their hash.
 *
 * @param a - First commit
 * @param b - Second commit
 * @returns True if commits have the same hash
 *
 * @example Compare two commits by hash
 * ```typescript
 * isSameCommit(commitA, commitB) // => true if commitA.hash === commitB.hash
 * ```
 */
declare function isSameCommit(a: GitCommit, b: GitCommit): boolean;
/**
 * Checks if a commit is a merge commit (has multiple parents).
 *
 * @param commit - Commit to check
 * @returns True if commit has more than one parent
 *
 * @example Check if commit is a merge commit
 * ```typescript
 * if (isMergeCommit(commit)) {
 *   console.log('Commit has parents:', commit.parents)
 * }
 * ```
 */
declare function isMergeCommit(commit: GitCommit): boolean;
/**
 * Checks if a commit is a root commit (has no parents).
 *
 * @param commit - Commit to check
 * @returns True if commit has no parents
 *
 * @example Check if commit is the initial commit
 * ```typescript
 * if (isRootCommit(commit)) {
 *   console.log('This is the initial commit')
 * }
 * ```
 */
declare function isRootCommit(commit: GitCommit): boolean;
/**
 * Extracts the scope from a commit subject if it follows conventional commit format.
 * Uses character-by-character parsing (no regex).
 *
 * @param subject - Commit subject line
 * @returns Scope string or undefined if no scope found
 *
 * @example Extract scope from conventional commit
 * extractScope('feat(lib-versioning): add git support') // 'lib-versioning'
 * extractScope('fix: resolve issue') // undefined
 */
declare function extractScope(subject: string): string | undefined;
/**
 * Extracts the type from a commit subject if it follows conventional commit format.
 * Uses character-by-character parsing (no regex).
 *
 * @param subject - Commit subject line
 * @returns Type string or undefined if no valid type found
 *
 * @example Extract type from conventional commit
 * extractType('feat(lib-versioning): add git support') // 'feat'
 * extractType('fix: resolve issue') // 'fix'
 * extractType('random message') // undefined
 */
declare function extractType(subject: string): string | undefined;

/**
 * Type of git reference.
 */
type GitRefType = 'branch' | 'tag' | 'remote' | 'head' | 'stash';
/**
 * A git reference.
 */
interface GitRef {
    /** Full reference name (e.g., refs/heads/main) */
    readonly fullName: string;
    /** Short reference name (e.g., main) */
    readonly name: string;
    /** Reference type */
    readonly type: GitRefType;
    /** Target commit hash */
    readonly commitHash: string;
    /** Remote name for remote refs */
    readonly remote?: string;
    /** Whether this is the current HEAD */
    readonly isHead?: boolean;
}
/**
 * Options for creating a git reference.
 */
interface CreateGitRefOptions {
    /** Full reference name */
    readonly fullName: string;
    /** Target commit hash */
    readonly commitHash: string;
    /** Whether this is the current HEAD */
    readonly isHead?: boolean;
}
/**
 * Creates a git reference from full name.
 * Parses the reference type from the full name.
 *
 * @param options - Reference creation options
 * @returns A new GitRef object
 *
 * @example Create a git reference from full name
 * const ref = createGitRef({
 *   fullName: 'refs/heads/main',
 *   commitHash: 'abc123...',
 * })
 */
declare function createGitRef(options: CreateGitRefOptions): GitRef;
/**
 * Checks if a reference is a branch.
 *
 * @param ref - Reference to check
 * @returns True if reference is a branch
 *
 * @example Check if reference is a branch
 * ```typescript
 * isBranchRef({ type: 'branch', name: 'main' }) // => true
 * ```
 */
declare function isBranchRef(ref: GitRef): boolean;
/**
 * Checks if a reference is a tag.
 *
 * @param ref - Reference to check
 * @returns True if reference is a tag
 *
 * @example Check if reference is a tag
 * ```typescript
 * isTagRef({ type: 'tag', name: 'v1.0.0' }) // => true
 * ```
 */
declare function isTagRef(ref: GitRef): boolean;
/**
 * Checks if a reference is a remote tracking branch.
 *
 * @param ref - Reference to check
 * @returns True if reference is a remote
 *
 * @example Check if reference is a remote tracking branch
 * ```typescript
 * isRemoteRef({ type: 'remote', name: 'main', remote: 'origin' }) // => true
 * ```
 */
declare function isRemoteRef(ref: GitRef): boolean;
/**
 * Checks if a reference points to the current HEAD.
 *
 * @param ref - Reference to check
 * @returns True if reference is HEAD
 *
 * @example Check if reference points to HEAD
 * ```typescript
 * isHeadRef({ type: 'head', name: 'HEAD' }) // => true
 * isHeadRef({ type: 'branch', name: 'main', isHead: true }) // => true
 * ```
 */
declare function isHeadRef(ref: GitRef): boolean;
/**
 * Gets the tracking remote for a reference.
 *
 * @param ref - Reference to check
 * @returns Remote name or undefined
 *
 * @example Get the remote for a reference
 * ```typescript
 * getRemote({ type: 'remote', name: 'main', remote: 'origin' }) // => 'origin'
 * getRemote({ type: 'branch', name: 'main' }) // => undefined
 * ```
 */
declare function getRemote(ref: GitRef): string | undefined;
/**
 * Builds a full reference name from type and name.
 *
 * @param type - Reference type
 * @param name - Reference name
 * @param remote - Remote name (for remote type)
 * @returns Full reference name
 *
 * @example Build full reference names from type and name
 * buildRefName('branch', 'main') // 'refs/heads/main'
 * buildRefName('tag', 'v1.0.0') // 'refs/tags/v1.0.0'
 * buildRefName('remote', 'main', 'origin') // 'refs/remotes/origin/main'
 */
declare function buildRefName(type: GitRefType, name: string, remote?: string): string;
/**
 * Compares two references by name (alphabetically).
 *
 * @param a - First reference
 * @param b - Second reference
 * @returns Comparison result (-1, 0, or 1)
 *
 * @example Sort references alphabetically by name
 * ```typescript
 * const refs = [refB, refA, refC]
 * refs.sort(compareRefsByName) // => [refA, refB, refC]
 * ```
 */
declare function compareRefsByName(a: GitRef, b: GitRef): number;
/**
 * Filters references by type.
 *
 * @param refs - References to filter
 * @param type - Type to filter by
 * @returns Filtered references
 *
 * @example Filter references by type
 * ```typescript
 * const branches = filterRefsByType(allRefs, 'branch')
 * const tags = filterRefsByType(allRefs, 'tag')
 * ```
 */
declare function filterRefsByType(refs: readonly GitRef[], type: GitRefType): readonly GitRef[];
/**
 * Filters references by remote.
 *
 * @param refs - References to filter
 * @param remote - Remote name to filter by
 * @returns Filtered references
 *
 * @example Filter references by remote
 * ```typescript
 * const originRefs = filterRefsByRemote(remoteRefs, 'origin')
 * const upstreamRefs = filterRefsByRemote(remoteRefs, 'upstream')
 * ```
 */
declare function filterRefsByRemote(refs: readonly GitRef[], remote: string): readonly GitRef[];

/**
 * Represents either a lightweight or annotated git tag.
 */
type GitTagType = 'lightweight' | 'annotated';
/**
 * A git tag with its metadata.
 */
interface GitTag {
    /** Tag name */
    readonly name: string;
    /** Target commit hash */
    readonly commitHash: string;
    /** Tag type */
    readonly type: GitTagType;
    /** Tag message (for annotated tags) */
    readonly message?: string;
    /** Tagger name (for annotated tags) */
    readonly taggerName?: string;
    /** Tagger email (for annotated tags) */
    readonly taggerEmail?: string;
    /** Tag date (ISO 8601 format, for annotated tags) */
    readonly tagDate?: string;
}
/**
 * Options for creating a lightweight tag.
 */
interface CreateLightweightTagOptions {
    /** Tag name */
    readonly name: string;
    /** Target commit hash */
    readonly commitHash: string;
}
/**
 * Options for creating an annotated tag.
 */
interface CreateAnnotatedTagOptions extends CreateLightweightTagOptions {
    /** Tag message */
    readonly message: string;
    /** Tagger name */
    readonly taggerName: string;
    /** Tagger email */
    readonly taggerEmail: string;
    /** Tag date (ISO 8601 format) */
    readonly tagDate: string;
}
/**
 * Creates a lightweight git tag.
 *
 * @param options - Tag creation options
 * @returns A new GitTag object
 *
 * @example Create a lightweight git tag
 * const tag = createLightweightTag({
 *   name: 'v1.0.0',
 *   commitHash: 'abc123...',
 * })
 */
declare function createLightweightTag(options: CreateLightweightTagOptions): GitTag;
/**
 * Creates an annotated git tag.
 *
 * @param options - Tag creation options
 * @returns A new GitTag object
 *
 * @example Create an annotated git tag with metadata
 * const tag = createAnnotatedTag({
 *   name: 'v1.0.0',
 *   commitHash: 'abc123...',
 *   message: 'Release v1.0.0',
 *   taggerName: 'John Doe',
 *   taggerEmail: 'john@example.com',
 *   tagDate: '2026-03-12T10:00:00Z',
 * })
 */
declare function createAnnotatedTag(options: CreateAnnotatedTagOptions): GitTag;
/**
 * Checks if a tag is annotated.
 *
 * @param tag - Tag to check
 * @returns True if tag is annotated
 *
 * @example Check if a tag is annotated
 * ```typescript
 * const tag = createAnnotatedTag({ name: 'v1.0.0', commitHash: 'abc123', message: 'Release' })
 * isAnnotatedTag(tag) // => true
 * ```
 */
declare function isAnnotatedTag(tag: GitTag): boolean;
/**
 * Checks if a tag is lightweight.
 *
 * @param tag - Tag to check
 * @returns True if tag is lightweight
 *
 * @example Check if a tag is lightweight
 * ```typescript
 * const tag = createLightweightTag({ name: 'v1.0.0', commitHash: 'abc123' })
 * isLightweightTag(tag) // => true
 * ```
 */
declare function isLightweightTag(tag: GitTag): boolean;
/**
 * Extracts version from tag name.
 * Handles common formats: v1.2.3, `@scope/package@1.2.3`, package@1.2.3
 * Uses character-by-character parsing (no regex).
 *
 * @param tagName - Tag name to parse
 * @returns The extracted version string or undefined if no version found
 *
 * @example Extract version from various tag formats
 * extractVersionFromTag('v1.2.3') // '1.2.3'
 * extractVersionFromTag('@scope/pkg@1.2.3') // '1.2.3'
 * extractVersionFromTag('release-1.2.3') // '1.2.3'
 */
declare function extractVersionFromTag(tagName: string): string | undefined;
/**
 * Extracts package name from tag name.
 * Handles formats like: `@scope/package@1.2.3`, package@1.2.3, package-v1.2.3
 * Uses character-by-character parsing (no regex).
 *
 * @param tagName - Tag name to parse
 * @returns The extracted package name or undefined if not found
 *
 * @example Extract package name from tag
 * extractPackageFromTag('@scope/pkg@1.2.3') // '@scope/pkg'
 * extractPackageFromTag('lib-utils@1.2.3') // 'lib-utils'
 * extractPackageFromTag('v1.2.3') // undefined
 */
declare function extractPackageFromTag(tagName: string): string | undefined;
/**
 * Builds a tag name from package name and version.
 *
 * @param packageName - Package name (e.g., '@scope/package' or 'package')
 * @param version - Version string (e.g., '1.2.3')
 * @param format - Tag format template, uses ${package} and ${version} placeholders
 * @returns Formatted tag name
 *
 * @example Build tag names with different formats
 * buildTagName('@scope/pkg', '1.2.3') // '@scope/pkg@1.2.3'
 * buildTagName('utils', '1.0.0', 'v${version}') // 'v1.0.0'
 * buildTagName('pkg', '2.0.0', '${package}-v${version}') // 'pkg-v2.0.0'
 */
declare function buildTagName(packageName: string, version: string, format?: string): string;
/**
 * Compares two tags by version (newest first).
 * Useful for sorting tags.
 *
 * @param a - First tag
 * @param b - Second tag
 * @returns Comparison result (-1, 0, or 1)
 *
 * @example Sort tags by version (newest first)
 * ```typescript
 * const tags = [tagV1, tagV2, tagV3]
 * tags.sort(compareTagsByVersion) // => [tagV3, tagV2, tagV1]
 * ```
 */
declare function compareTagsByVersion(a: GitTag, b: GitTag): number;

export { buildRefName, buildTagName, compareRefsByName, compareTagsByVersion, createAnnotatedTag, createGitCommit, createGitRef, createLightweightTag, extractPackageFromTag, extractScope, extractType, extractVersionFromTag, filterRefsByRemote, filterRefsByType, getRemote, getShortHash, isAnnotatedTag, isBranchRef, isHeadRef, isLightweightTag, isMergeCommit, isRemoteRef, isRootCommit, isSameCommit, isTagRef };
export type { CreateAnnotatedTagOptions, CreateGitCommitOptions, CreateGitRefOptions, CreateLightweightTagOptions, GitCommit, GitRef, GitRefType, GitTag, GitTagType };