import { CommitSource } from '../../commits/classify';
import { Schema, ValidationResult } from '../../_dependencies/@hyperfrontend/json-utils/index.js';

/**
 * Commit Reference
 *
 * Represents a reference to a git commit in a changelog item.
 */
interface CommitRef {
    /** Full commit hash */
    readonly hash: string;
    /** Short commit hash (typically 7 characters) */
    readonly shortHash: string;
    /** URL to the commit (e.g., GitHub commit link) */
    readonly url?: string;
}
/**
 * Issue/PR Reference
 *
 * Represents a reference to an issue or pull request.
 */
interface IssueRef {
    /** Issue or PR number */
    readonly number: number;
    /** URL to the issue/PR */
    readonly url?: string;
    /** Type of reference */
    readonly type: 'issue' | 'pull-request';
}
/**
 * Creates a commit reference from a full hash.
 *
 * @param hash - The full commit hash
 * @param url - Optional URL to the commit
 * @returns A new CommitRef object with both full and short hash
 *
 * @example Creating a commit reference
 * ```typescript
 * const ref = createCommitRef('abc1234def5678', 'https://github.com/org/repo/commit/abc1234def5678')
 * // => { hash: 'abc1234def5678', shortHash: 'abc1234', url: 'https://...' }
 * ```
 */
declare function createCommitRef(hash: string, url?: string): CommitRef;
/**
 * Creates an issue reference.
 *
 * @param number - The issue or PR number
 * @param type - The type of reference ('issue' or 'pull-request')
 * @param url - Optional URL to the issue or PR
 * @returns A new IssueRef object
 *
 * @example Creating issue and PR references
 * ```typescript
 * const issueRef = createIssueRef(42, 'issue', 'https://github.com/org/repo/issues/42')
 * // => { number: 42, type: 'issue', url: 'https://...' }
 *
 * const prRef = createIssueRef(123, 'pull-request')
 * // => { number: 123, type: 'pull-request', url: undefined }
 * ```
 */
declare function createIssueRef(number: number, type?: 'issue' | 'pull-request', url?: string): IssueRef;
/**
 * Extracts the short hash from a full commit hash.
 *
 * @param hash - The full commit hash
 * @returns The first 7 characters of the hash
 *
 * @example Extracting short hash from full hash
 * ```typescript
 * getShortHash('abc1234def5678901234567890')
 * // => 'abc1234'
 * ```
 */
declare function getShortHash(hash: string): string;

/**
 * Changelog Section Types
 *
 * Categories for grouping changes in a changelog entry.
 */
type ChangelogSectionType = 'breaking' | 'features' | 'fixes' | 'performance' | 'documentation' | 'deprecations' | 'refactoring' | 'tests' | 'build' | 'ci' | 'chores' | 'other';
/**
 * Maps section headings to their canonical types.
 * Used during parsing to normalize different heading styles.
 */
declare const SECTION_TYPE_MAP: Record<string, ChangelogSectionType>;
/**
 * Standard section headings for serialization.
 * Maps section types to their preferred heading text.
 */
declare const SECTION_HEADINGS: Record<ChangelogSectionType, string>;
/**
 * Determines the section type from a heading string.
 * Returns 'other' if the heading is not recognized.
 *
 * @param heading - The heading string to parse
 * @returns The corresponding ChangelogSectionType
 *
 * @example Mapping heading strings to section types
 * ```typescript
 * getSectionType('Added')
 * // => 'features'
 *
 * getSectionType('Bug Fixes')
 * // => 'fixes'
 *
 * getSectionType('Custom Section')
 * // => 'other'
 * ```
 */
declare function getSectionType(heading: string): ChangelogSectionType;

/**
 * Changelog Item
 *
 * Represents an individual change within a changelog section.
 */
interface ChangelogItem {
    /** Scope (e.g., "api", "cli") */
    readonly scope?: string;
    /** Description of the change */
    readonly description: string;
    /** Commit references */
    readonly commits: readonly CommitRef[];
    /** Issue/PR references */
    readonly references: readonly IssueRef[];
    /** Whether this is a breaking change */
    readonly breaking: boolean;
    /** Classification source (for auditing/debugging) */
    readonly source?: CommitSource;
    /** Whether this is an indirect change (dependency or infrastructure) */
    readonly indirect?: boolean;
}
/**
 * Changelog Section
 *
 * Represents a category of changes (Features, Bug Fixes, etc.)
 */
interface ChangelogSection {
    /** Section type (features, fixes, etc.) */
    readonly type: ChangelogSectionType;
    /** Section heading as it appears in file */
    readonly heading: string;
    /** Individual change items */
    readonly items: readonly ChangelogItem[];
}
/**
 * Changelog Entry
 *
 * Represents a single version entry in a changelog.
 */
interface ChangelogEntry {
    /** Version string (e.g., "1.2.3") */
    readonly version: string;
    /** Release date (ISO format or null for unreleased) */
    readonly date: string | null;
    /** Whether this is an unreleased/upcoming section */
    readonly unreleased: boolean;
    /** Compare URL (e.g., GitHub compare link) */
    readonly compareUrl?: string;
    /** Grouped changes by category */
    readonly sections: readonly ChangelogSection[];
    /** Raw text for entries that couldn't be parsed structurally */
    readonly rawContent?: string;
}
/**
 * Creates a new changelog item.
 *
 * @param description - The description text of the change
 * @param options - Optional configuration for scope, commits, references, and breaking flag
 * @returns A new ChangelogItem object
 *
 * @example Creating a changelog item with options
 * ```typescript
 * const item = createChangelogItem('Add user authentication', {
 *   scope: 'auth',
 *   breaking: false,
 *   references: [{ number: 42, type: 'issue' }],
 * })
 * ```
 */
declare function createChangelogItem(description: string, options?: Partial<Omit<ChangelogItem, 'description'>>): ChangelogItem;
/**
 * Creates a new changelog section.
 *
 * @param type - The type of section (features, fixes, breaking, etc.)
 * @param heading - The display heading for the section
 * @param items - Optional array of changelog items in this section
 * @returns A new ChangelogSection object
 *
 * @example Creating a features section with items
 * ```typescript
 * const section = createChangelogSection('features', 'Added', [
 *   createChangelogItem('New dashboard widget'),
 * ])
 * ```
 */
declare function createChangelogSection(type: ChangelogSectionType, heading: string, items?: readonly ChangelogItem[]): ChangelogSection;
/**
 * Creates a new changelog entry.
 *
 * @param version - The version string (e.g., '1.0.0')
 * @param options - Optional configuration for date, sections, and other properties
 * @returns A new ChangelogEntry object
 *
 * @example Creating a changelog entry with date and sections
 * ```typescript
 * const entry = createChangelogEntry('1.0.0', {
 *   date: '2024-01-15',
 *   sections: [createChangelogSection('features', 'Added', items)],
 * })
 * ```
 */
declare function createChangelogEntry(version: string, options?: Partial<Omit<ChangelogEntry, 'version'>>): ChangelogEntry;
/**
 * Creates an unreleased changelog entry.
 *
 * @param sections - Optional array of changelog sections
 * @returns A new ChangelogEntry object marked as unreleased
 *
 * @example Creating an unreleased entry
 * ```typescript
 * const unreleased = createUnreleasedEntry([
 *   createChangelogSection('features', 'Added', [item]),
 * ])
 * // => { version: 'Unreleased', date: null, unreleased: true, sections: [...] }
 * ```
 */
declare function createUnreleasedEntry(sections?: readonly ChangelogSection[]): ChangelogEntry;

/**
 * Changelog Link
 *
 * Represents a link defined in the changelog header or elsewhere.
 */
interface ChangelogLink {
    /** Link label */
    readonly label: string;
    /** Link URL */
    readonly url: string;
}
/**
 * Changelog Header
 *
 * The header section of a changelog file.
 */
interface ChangelogHeader {
    /** Title (e.g., "# Changelog") */
    readonly title: string;
    /** Description paragraphs between title and first entry */
    readonly description: readonly string[];
    /** Any links defined in header */
    readonly links: readonly ChangelogLink[];
}
/**
 * Changelog Format
 *
 * Detected format/style of the changelog file.
 */
type ChangelogFormat = 'keep-a-changelog' | 'conventional' | 'custom' | 'unknown';
/**
 * Changelog Metadata
 *
 * Additional information extracted during parsing.
 */
interface ChangelogMetadata {
    /** Detected changelog format/style */
    readonly format: ChangelogFormat;
    /** Whether the file follows conventional changelog spec */
    readonly isConventional: boolean;
    /** Repository URL if detected */
    readonly repositoryUrl?: string;
    /** Package name if detected */
    readonly packageName?: string;
    /** Parser warnings/notes */
    readonly warnings: readonly string[];
}
/**
 * Changelog
 *
 * Complete representation of a CHANGELOG.md file.
 * Designed for lossless round-tripping: parse -> modify -> serialize.
 */
interface Changelog {
    /** Original file path (if parsed from file) */
    readonly source?: string;
    /** File header/preamble content */
    readonly header: ChangelogHeader;
    /** Version entries, ordered newest first */
    readonly entries: readonly ChangelogEntry[];
    /** Additional metadata extracted during parsing */
    readonly metadata: ChangelogMetadata;
}
/**
 * Creates a new changelog with default values.
 *
 * @param options - Optional configuration to customize the changelog
 * @returns A new Changelog object with the specified options or defaults
 *
 * @example Creating a changelog with custom source
 * ```typescript
 * const changelog = createChangelog({ source: 'CHANGELOG.md' })
 * // => { source: 'CHANGELOG.md', header: { title: '# Changelog', ... }, entries: [] }
 * ```
 */
declare function createChangelog(options?: Partial<Changelog>): Changelog;
/**
 * Creates a new empty changelog with standard header.
 *
 * @returns A new empty Changelog with Keep a Changelog format
 *
 * @example Creating an empty changelog with standard header
 * ```typescript
 * const changelog = createEmptyChangelog()
 * // => Changelog with standard Keep a Changelog header and no entries
 * ```
 */
declare function createEmptyChangelog(): Changelog;
/**
 * Creates a changelog link.
 *
 * @param label - The display text for the link
 * @param url - The URL the link points to
 * @returns A new ChangelogLink object
 *
 * @example Creating a version comparison link
 * ```typescript
 * const link = createChangelogLink('1.0.0', 'https://github.com/org/repo/compare/v0.9.0...v1.0.0')
 * // => { label: '1.0.0', url: 'https://github.com/...' }
 * ```
 */
declare function createChangelogLink(label: string, url: string): ChangelogLink;

/**
 * Schema compatibility check result.
 */
interface CompatibilityResult {
    /** Whether schemas are compatible */
    readonly compatible: boolean;
    /** List of schema differences found */
    readonly differences: readonly SchemaDifference[];
}
/**
 * A single schema difference.
 */
interface SchemaDifference {
    /** JSON path where difference was found */
    readonly path: string;
    /** Type of difference */
    readonly type: 'type-mismatch' | 'missing-property' | 'extra-property';
    /** Type in source schema */
    readonly sourceType?: string;
    /** Type in target schema */
    readonly targetType?: string;
}
/**
 * JSON Schema for a complete Changelog document.
 * Used for validation and format compatibility checking.
 */
declare const changelogSchema: Schema;
/**
 * Validates a changelog object against the schema.
 *
 * @param changelog - The changelog object to validate
 * @returns Validation result with any errors
 *
 * @example Validating a changelog object
 * ```ts
 * const result = validateChangelog(myChangelog)
 * if (!result.valid) {
 *   console.log('Validation errors:', result.errors)
 * }
 * ```
 */
declare function validateChangelog(changelog: unknown): ValidationResult;
/**
 * Checks if two changelogs have compatible schemas.
 * Used to detect format incompatibilities before merge/compare.
 *
 * @param source - The source changelog
 * @param target - The target changelog
 * @returns Compatibility result with any differences found
 *
 * @example Checking schema compatibility before merge
 * ```ts
 * const result = checkSchemaCompatibility(mainChangelog, branchChangelog)
 * if (!result.compatible) {
 *   console.log('Schema differences:', result.differences)
 * }
 * ```
 */
declare function checkSchemaCompatibility(source: Changelog, target: Changelog): CompatibilityResult;

export { SECTION_HEADINGS, SECTION_TYPE_MAP, changelogSchema, checkSchemaCompatibility, createChangelog, createChangelogEntry, createChangelogItem, createChangelogLink, createChangelogSection, createCommitRef, createEmptyChangelog, createIssueRef, createUnreleasedEntry, getSectionType, getShortHash, validateChangelog };
export type { Changelog, ChangelogEntry, ChangelogFormat, ChangelogHeader, ChangelogItem, ChangelogLink, ChangelogMetadata, ChangelogSection, ChangelogSectionType, CommitRef, CompatibilityResult, IssueRef, SchemaDifference };