import { Directory, File } from './entries.ts';
import type { Cache } from './Cache.ts';
import type { ExportHistoryOptions, ExportHistoryGenerator, GitAuthor } from './types.ts';
export type GitHostType = 'github' | 'gitlab' | 'bitbucket' | 'pierre';
export type RepositoryReleaseSource = {
    mode?: 'remote';
} | {
    mode: 'local';
    version: string;
};
export interface RepositoryConfig {
    /** The base URL of the repository host or full repository URL. */
    baseUrl: string;
    /** The type of Git host. */
    host: GitHostType;
    /** Optional owner and repository, overrides parsing from `baseUrl` when set. */
    owner?: string;
    /** Optional repository name, overrides parsing from `baseUrl` when set. */
    repository?: string;
    /** Optional default branch/ref, used for URLs. */
    branch?: string;
    /** Optional default path prefix inside the repository. */
    path?: string;
    /** Internal release metadata source mode. */
    releaseSource?: RepositoryReleaseSource;
    /** Optional cache provider for repository-backed operations. */
    cache?: Cache;
}
export interface BaseRepositoryOptions {
    /**
     * Local path or remote repository URL/specifier.
     * Only use trusted configuration here.
     * If this comes from user input, the user can choose which repository the
     * server reads:
     * - local paths and `file://` URLs can point at another local repository
     * - remote URLs can trigger fetches/clones to attacker-chosen remotes
     * The risk is unintended file access or outbound git/network access.
     */
    path: string;
    /** Git reference to use for git operations and default URLs. */
    ref?: string;
    /**
     * When true (default for remote repositories), use git clone operations.
     * When false, use the host API (virtual).
     */
    clone?: boolean;
    /** Internal release metadata source mode. */
    releaseSource?: RepositoryReleaseSource;
    /** Optional cache provider for repository-backed operations. */
    cache?: Cache;
}
export interface CloneRepositoryOptions extends BaseRepositoryOptions {
    /** Clone remote repositories into a local cache. */
    clone?: true;
    /** Shallow clone depth (undefined = full history). */
    depth?: number;
    /** Sparse checkout paths for large repositories. */
    sparse?: string[];
}
export interface VirtualRepositoryOptions extends BaseRepositoryOptions {
    /** Disable cloning and use the host API. */
    clone: false;
    /** Access token for remote API requests. */
    token?: string;
}
export type RepositoryOptions = CloneRepositoryOptions | VirtualRepositoryOptions;
/** Explicit repository instances accepted by higher-level APIs. */
export type RepositoryInput = Repository;
export type UnsafeRepositoryInput = Repository | RepositoryConfig | RepositoryOptions | string;
export type RepositoryExportHistoryOptions = ExportHistoryOptions & {
    /** Filter the report to only include changes for this export name. */
    exportName?: string;
};
export interface GetFileUrlOptions {
    /** The path to the file within the repository. */
    path: string;
    /** The file URL type. */
    type?: 'source' | 'edit' | 'raw' | 'blame' | 'history';
    /** A reference to a branch, tag, or commit. */
    ref?: string;
    /** Single line or range of start and end lines to link to. */
    line?: number | [number, number];
}
export interface GetDirectoryUrlOptions {
    /** The path to the directory within the repository. */
    path: string;
    /** The directory URL type. */
    type?: 'source' | 'history';
    /** A reference to a branch, tag, or commit. */
    ref?: string;
}
export type ReleaseSpecifier = 'latest' | 'next' | `v${string}` | string;
export interface GetReleaseOptions {
    /** Which release to resolve. */
    release?: ReleaseSpecifier;
    /**
     * Filter releases by a specific package name.
     *
     * When provided, only releases whose tag or name start with `${packageName}@`
     * will be considered. This is useful for repositories that publish multiple
     * packages (e.g. `renoun`, `@renoun/mdx`) from a single Git releases feed.
     */
    packageName?: string;
    /** Force a refresh of the cached release metadata. */
    refresh?: boolean;
}
export interface GetReleaseUrlOptions extends GetReleaseOptions {
    /** Select a downloadable asset by heuristic or matcher. */
    asset?: true | string | RegExp;
    /** Link to the release source archive. */
    source?: 'zip' | 'tar';
    /** Link to a compare view from this ref to the resolved release. */
    compare?: string;
}
export interface ReleaseAsset {
    /** Asset display name. */
    name: string;
    /** Size of the asset in bytes, when provided. */
    size?: number;
    /** MIME type of the asset, when provided. */
    contentType?: string;
    /** Direct download URL for the asset. */
    downloadUrl: string;
}
export interface Release {
    /** The release tag name. */
    tagName?: string;
    /** The release title. */
    name?: string;
    /** The HTML URL to the release or releases overview when unavailable. */
    htmlUrl: string;
    /** ISO timestamp for when the release was published, if provided by the host. */
    publishedAt?: string;
    /** Indicates whether the release is marked as a draft. */
    isDraft: boolean;
    /** Indicates whether the release is marked as a prerelease. */
    isPrerelease: boolean;
    /** True when the response falls back to a generic releases page. */
    isFallback: boolean;
    /** Downloadable assets published alongside the release. */
    assets: ReleaseAsset[];
    /** Direct link to the tarball source archive, when available. */
    tarballUrl?: string;
    /** Direct link to the zipball source archive, when available. */
    zipballUrl?: string;
}
export interface GetCommitUrlOptions {
    /** The full or abbreviated commit SHA to link to. */
    sha: string;
}
export interface GetReleaseTagUrlOptions {
    /** The tag name of the release (e.g. "v1.2.3" or "r123"). */
    tag: string;
}
export interface GetIssueUrlOptions {
    /** The title of the issue. */
    title: string;
    /** The description of the issue. */
    description?: string;
    /** The labels to assign to the issue. */
    labels?: string[];
}
/** Parsed git specifier. */
export interface ParsedGitSpecifier {
    /** The host of the repository. */
    host: GitHostType;
    /** The owner of the repository. */
    owner: string;
    /** The repository name. */
    repo: string;
    /** Optional ref (branch/tag/sha). */
    ref?: string;
    /** Optional default path after the ref (e.g. "@main/docs"). */
    path?: string;
}
/**
 * Parse a git specifier string into a `ParsedGitSpecifier` object.
 *
 * - If both '@' and '#' appear, the earliest is used as the ref separator.
 * - A trailing path is only allowed AFTER a ref (i.e. "@ref/path").
 * - Default host for bare "owner/repo" is "github".
 *
 * Examples:
 *   - "owner/repo"
 *   - "github:owner/repo"
 *   - "owner/repo@ref"
 *   - "owner/repo#ref"
 *   - "gitlab:group/subgroup/repo@ref/docs"
 */
export declare function parseGitSpecifier(input: string): ParsedGitSpecifier;
export declare class Repository {
    #private;
    static resolve(repository?: RepositoryInput, _cache?: Cache): Repository | undefined;
    /**
     * Parses raw repository locators and config objects.
     * Only use this with trusted application configuration, never end-user input.
     */
    static resolveUnsafe(repository?: UnsafeRepositoryInput, cache?: Cache): Repository | undefined;
    /** Creates a repository rooted at a local checkout. */
    static local(path?: string, options?: Omit<CloneRepositoryOptions, 'path'>): Repository;
    /** Creates a repository rooted at a remote git host or remote URL. */
    static remote(repository: string | RepositoryConfig | (RepositoryOptions & {
        path: string;
    })): Repository;
    /** Prefer `Repository.local(...)` or `Repository.remote(...)` for new code. */
    constructor(repository?: RepositoryOptions | RepositoryConfig | string);
    /** Returns a directory scoped to this repository. */
    getDirectory(path?: string): Directory;
    /** Returns a file scoped to this repository. */
    getFile<Path extends string>(path: Path): File<Record<string, any>, Path>;
    /** Get the first git commit date of a path in this repository. */
    getFirstCommitDate(path: string): Promise<Date | undefined>;
    /** Get the last git commit date of a path in this repository. */
    getLastCommitDate(path: string): Promise<Date | undefined>;
    /** Get the git authors for a path in this repository. */
    getAuthors(path: string): Promise<GitAuthor[]>;
    /** Get export history for this repository. */
    getExportHistory(options?: RepositoryExportHistoryOptions): ExportHistoryGenerator;
    /** Returns the string representation of the repository. */
    toString(): string;
    /** Constructs a URL pointing to a specific commit in the repository. */
    getCommitUrl(options: GetCommitUrlOptions): string;
    /** Constructs a URL pointing to a specific release tag in the repository. */
    getReleaseTagUrl(options: GetReleaseTagUrlOptions): string;
    /** Constructs a new issue URL for the repository. */
    getIssueUrl(options: GetIssueUrlOptions): string;
    /** Constructs a URL for a file in the repository. */
    getFileUrl(options: GetFileUrlOptions): string;
    /** Constructs a URL for a directory in the repository. */
    getDirectoryUrl(options: GetDirectoryUrlOptions): string;
    /** Retrieve metadata about a release for the repository. */
    getRelease(options?: GetReleaseOptions): Promise<Release>;
    /** Retrieve a URL associated with a release (asset, archive, compare, or HTML). */
    getReleaseUrl(options?: GetReleaseUrlOptions): Promise<string>;
}