import GraphNode from '../entities/GraphNode.ts';
/**
 * NUL byte (0x00) - Delimits commit records in git log output.
 *
 * Git commit messages cannot contain NUL bytes - git rejects them at commit time.
 * This makes NUL a perfectly safe delimiter that cannot appear in any field,
 * eliminating the possibility of message injection attacks.
 *
 * The git log format produces records in this exact structure:
 *
 * ```
 * <SHA>\n
 * <author>\n
 * <date>\n
 * <parents (space-separated)>\n
 * <message body (may contain newlines)>\x00
 * ```
 *
 * Fields within each record are separated by newlines. The first 4 lines are
 * fixed fields (SHA, author, date, parents), and all remaining content up to
 * the NUL terminator is the message body.
 *
 * @see https://git-scm.com/docs/git-log (see -z option documentation)
 */
export declare const RECORD_SEPARATOR = "\0";
/**
 * Parser for git log output streams.
 *
 * Handles UTF-8 decoding, record splitting, and node instantiation as separate
 * concerns. Designed as an injectable dependency for RuntimeHost to enable
 * testing and alternative implementations.
 *
 * **Binary-First Processing**: The parser works directly with binary data for
 * performance. Uint8Array.indexOf(0) scans bytes without UTF-8 decoding
 * overhead, and byte-level comparison is faster than character-level.
 *
 * UTF-8 decoding only happens once per complete record, not during scanning.
 * This is especially beneficial for large commit histories where most of the
 * data is being scanned to find record boundaries.
 *
 * **Log Format Contract**: Each record is NUL-terminated and contains fields
 * separated by newlines:
 * 1. SHA (40 hex chars)
 * 2. Author name
 * 3. Date string
 * 4. Parent SHAs (space-separated, empty string for root commits)
 * 5. Message body (may span multiple lines, everything until NUL terminator)
 *
 * **Why NUL delimiter?** Git commit messages cannot contain NUL bytes - git
 * rejects them at commit time. This makes NUL a perfectly safe record delimiter
 * that eliminates parsing ambiguity, unlike 0x1E which can theoretically appear
 * in message content.
 *
 * @example
 * // Basic usage
 * const parser = new GitLogParser();
 * for await (const node of parser.parse(stream)) {
 *   console.log(node.sha, node.message);
 * }
 *
 * @example
 * // Inject into RuntimeHost for testing
 * const mockParser = { parse: async function*() { yield mockNode; } };
 * const graph = new RuntimeHost({ persistence, parser: mockParser });
 */
export default class GitLogParser {
    /**
     * Parses a stream of git log output and yields GraphNode instances.
     *
     * **Binary-first processing for performance**:
     * - Accepts Uint8Array or string chunks
     * - Finds NUL bytes (0x00) directly in binary using Uint8Array.indexOf(0)
     * - UTF-8 decoding only happens for complete records, not during scanning
     *
     * Handles:
     * - UTF-8 sequences split across chunk boundaries (via binary accumulation)
     * - Records terminated by NUL bytes (0x00)
     * - Streaming without loading entire history into memory
     * - Backwards compatibility with string chunks
     * - Cancellation via AbortSignal
     *
     * @param stream - The git log output stream. May yield Uint8Array or string chunks.
     * @param options - Parse options
     * @yields Parsed graph nodes. Invalid records are silently skipped.
     * @throws {OperationAbortedError} If signal is aborted during parsing
     *
     * @example
     * const stream = persistence.logNodesStream({ ref: 'main', limit: 100, format });
     * for await (const node of parser.parse(stream)) {
     *   console.log(node.sha);
     * }
     *
     * @example
     * // With cancellation support
     * const controller = new AbortController();
     * for await (const node of parser.parse(stream, { signal: controller.signal })) {
     *   console.log(node.sha);
     * }
     */
    parse(stream: AsyncIterable<Uint8Array | string>, { signal }?: {
        signal?: AbortSignal;
    }): AsyncGenerator<GraphNode>;
    /**
     * Parses any remaining bytes after the stream ends (final record without trailing NUL).
     */
    private _parseTrailing;
    /**
     * Extracts complete NUL-delimited records from the binary buffer.
     *
     * @param buffer - Accumulated binary data
     * @param signal - Optional cancellation signal
     * @returns Parsed nodes and leftover bytes
     */
    private _drainBuffer;
    /**
     * Parses a single record block into a GraphNode.
     *
     * Expected format (fields separated by newlines):
     * - Line 0: SHA (required, non-empty)
     * - Line 1: Author name
     * - Line 2: Date string
     * - Line 3: Parent SHAs (space-separated, may be empty for root commits)
     * - Lines 4+: Message body (preserved exactly, not trimmed)
     *
     * The block should not include the trailing NUL terminator - that is stripped
     * by the parse() method before calling parseNode().
     *
     * @param block - Raw block text (without trailing NUL terminator)
     * @returns Parsed node, or null if the block is malformed
     *   or has an empty message (GraphNode requires non-empty message)
     *
     * @example
     * const block = 'abc123\nAuthor\n2026-01-28\nparent1 parent2\nCommit message';
     * const node = parser.parseNode(block);
     * // node.sha === 'abc123'
     * // node.parents === ['parent1', 'parent2']
     */
    parseNode(block: string): GraphNode | null;
}
