import { CommitRef, IssueRef, Changelog } from '../models';

/**
 * Result of {@link parseBreakingFromItem}: the breaking flag plus the item
 * text left once its leading markers are removed.
 */
type BreakingFromItem = {
    /** Whether the item opened with at least one breaking marker */
    breaking: boolean;
    /** The item text with every leading breaking marker stripped */
    text: string;
};
/**
 * Parses the breaking-change markers a changelog item can open with, lifting
 * them out of the text and onto a flag. Serializing re-emits exactly one
 * marker, so an item survives a parse then serialize round trip unchanged; a
 * run of markers left behind by earlier round trips collapses back to a single
 * flag.
 *
 * Recognized openers, case-insensitive and repeatable: `**BREAKING**`,
 * `**BREAKING:**`, `[BREAKING]`, `⚠️ BREAKING:`, a bare `BREAKING:`, and the
 * `BREAKING CHANGE`/`BREAKING CHANGES` spelling of each. A bare mention needs
 * its colon to count, so prose such as `Breaking apart the parser` is left
 * alone. Scanning is character-by-character to stay ReDoS-safe.
 *
 * @param text - The changelog item text, without its list marker
 * @returns The breaking flag and the text that follows the markers
 *
 * @example Lifting markers out of item text
 * ```typescript
 * parseBreakingFromItem('**BREAKING** **BREAKING:** drop the sync open')
 * // => { breaking: true, text: 'drop the sync open' }
 *
 * parseBreakingFromItem('add a retry budget')
 * // => { breaking: false, text: 'add a retry budget' }
 * ```
 */
declare function parseBreakingFromItem(text: string): BreakingFromItem;

/**
 * Token Types
 */
type TokenType = 'heading-1' | 'heading-2' | 'heading-3' | 'heading-4' | 'list-item' | 'link-text' | 'link-url' | 'text' | 'newline' | 'blank-line' | 'bold' | 'code' | 'eof';
/**
 * Represents a single parsed token from the changelog markdown.
 */
interface Token {
    /** The type classification of the token */
    readonly type: TokenType;
    /** The raw text content of the token */
    readonly value: string;
    /** Line number where the token appears (1-indexed) */
    readonly line: number;
    /** Column position where the token starts (1-indexed) */
    readonly column: number;
}
/**
 * Tokenizes a changelog markdown string into tokens.
 *
 * @param input - The markdown content to tokenize
 * @returns Array of tokens
 * @throws {Error} If input exceeds maximum length
 *
 * @example Tokenizing changelog markdown
 * ```typescript
 * const tokens = tokenize('# Changelog\n\n## [1.0.0]\n- Added feature')
 * // => [{ type: 'heading-1', value: 'Changelog', ... }, { type: 'heading-2', ... }, ...]
 * ```
 */
declare function tokenize(input: string): Token[];

/**
 * Parsed version-line metadata extracted from a CHANGELOG section heading.
 */
type ParsedVersionHeading = {
    /** The parsed version string */
    version: string;
    /** The parsed date in YYYY-MM-DD format, or null if not found */
    date: string | null;
    /** Optional URL for comparing versions */
    compareUrl?: string;
};
/**
 * Parses a version string from a heading.
 * Examples: "1.2.3", "v1.2.3", "[1.2.3]", "1.2.3 - 2024-01-01"
 *
 * @param heading - The heading string to parse
 * @returns An object containing the parsed version, date, and optional compareUrl
 *
 * @example Parsing version headings
 * ```typescript
 * parseVersionFromHeading('[1.2.3] - 2024-01-15')
 * // => { version: '1.2.3', date: '2024-01-15', compareUrl: undefined }
 *
 * parseVersionFromHeading('v2.0.0')
 * // => { version: '2.0.0', date: null, compareUrl: undefined }
 * ```
 */
declare function parseVersionFromHeading(heading: string): ParsedVersionHeading;
/**
 * Parses commit references from a line.
 * Examples: (abc1234), [abc1234], commit abc1234
 *
 * @param text - The text to parse for commit references
 * @param baseUrl - Optional base URL for constructing commit links
 * @returns An array of parsed CommitRef objects
 *
 * @example Parsing commit references from text
 * ```typescript
 * parseCommitRefs('Fixed bug (abc1234)', 'https://github.com/org/repo')
 * // => [{ hash: 'abc1234', shortHash: 'abc1234', url: 'https://github.com/org/repo/commit/abc1234' }]
 * ```
 */
declare function parseCommitRefs(text: string, baseUrl?: string): CommitRef[];
/**
 * Parses issue/PR references from a line.
 * Examples: #123, GH-123, closes #123
 *
 * @param text - The text to parse for issue references
 * @param baseUrl - Optional base URL for constructing issue links
 * @returns An array of parsed IssueRef objects
 *
 * @example Parsing issue references from text
 * ```typescript
 * parseIssueRefs('Closes #42 and PR #123', 'https://github.com/org/repo')
 * // => [{ number: 42, type: 'issue', url: '...' }, { number: 123, type: 'pull-request', url: '...' }]
 * ```
 */
declare function parseIssueRefs(text: string, baseUrl?: string): IssueRef[];
/**
 * Result of {@link parseScopeFromItem}: optional scope plus the description
 * that follows it.
 */
type ScopeFromItem = {
    /** Optional scope extracted from the text */
    scope?: string;
    /** The description text after the scope */
    description: string;
};
/**
 * Parses the scope from a changelog item.
 * Example: "**scope:** description" -> { scope: "scope", description: "description" }
 *
 * @param text - The text to parse for scope
 * @returns An object with optional scope and the description
 *
 * @example Parsing scope from changelog items
 * ```typescript
 * parseScopeFromItem('**api:** Add new endpoint')
 * // => { scope: 'api', description: 'Add new endpoint' }
 *
 * parseScopeFromItem('Simple change without scope')
 * // => { scope: undefined, description: 'Simple change without scope' }
 * ```
 */
declare function parseScopeFromItem(text: string): ScopeFromItem;

/**
 * Parses a changelog markdown string into a Changelog object.
 *
 * @param content - The markdown content to parse
 * @param source - Optional source file path
 * @returns Parsed Changelog object
 *
 * @example Parsing a changelog markdown string
 * ```typescript
 * const markdown = `# Changelog
 *
 * ## [1.0.0] - 2024-01-15
 *
 * ### Added
 * - Initial release`
 *
 * const changelog = parseChangelog(markdown, 'CHANGELOG.md')
 * // => { header: { title: '# Changelog', ... }, entries: [{ version: '1.0.0', ... }] }
 * ```
 */
declare function parseChangelog(content: string, source?: string): Changelog;

export { parseBreakingFromItem, parseChangelog, parseCommitRefs, parseIssueRefs, parseScopeFromItem, parseVersionFromHeading, tokenize };
export type { BreakingFromItem, Token, TokenType };