/**
 * Branch Diff Utility
 *
 * Bridges merge preview API data with existing Puck diff utilities
 * for branch-level comparison. Provides document-level and aggregate
 * merge comparison capabilities.
 */
import type { PuckData } from '@pantheon-systems/css-client';
import type { ComponentDiffWithPosition } from '../../core/types.js';
/**
 * Comparison result for a single document between source and target branches.
 */
export interface BranchDocumentComparison {
    /** Document identifier. */
    documentId: string;
    /** Document path (e.g., '/pages/home'). */
    documentPath: string;
    /** Whether the snapshots were detected as PuckData. */
    isPuckData: boolean;
    /** Component-level diffs with position information. */
    diffs: ComponentDiffWithPosition[];
    /** Aggregated change counts for this document. */
    counts: {
        added: number;
        removed: number;
        modified: number;
        unchanged: number;
    };
}
/**
 * Aggregated comparison result across all documents in a branch merge.
 */
export interface BranchMergeComparison {
    /** Per-document comparison results. */
    documents: BranchDocumentComparison[];
    /** Aggregated change counts across all documents. */
    totalCounts: {
        added: number;
        removed: number;
        modified: number;
        unchanged: number;
    };
    /** Total number of documents compared. */
    documentCount: number;
    /** Number of documents that have at least one non-unchanged diff. */
    changedDocumentCount: number;
}
/**
 * Input summary for a document to be diffed between branches.
 */
export interface DocumentDiffSummary {
    /** Document identifier. */
    documentId: string;
    /** Document path (e.g., '/pages/home'). */
    documentPath: string;
    /** Snapshot from the source branch (may be PuckData or regular JSON). */
    sourceSnapshot: unknown;
    /** Snapshot from the target branch (may be PuckData or regular JSON). */
    targetSnapshot: unknown;
}
/** Empty PuckData used as a stand-in for null snapshots. */
export declare const EMPTY_PUCK_DATA: PuckData;
/**
 * Detects whether the given value is a PuckData structure.
 *
 * A value is considered PuckData when it is a non-null object with a
 * `content` property that is an array and a `root` property that is
 * an object.
 *
 * @param data - The value to inspect.
 * @returns `true` if the value matches the PuckData shape.
 *
 * @example
 * ```typescript
 * if (isPuckData(snapshot)) {
 *   const diffs = diffPuckDataWithPositions(before, snapshot);
 * }
 * ```
 */
export declare function isPuckData(data: unknown): boolean;
/**
 * Creates a comparison for a single document between source and target
 * branch snapshots.
 *
 * Behaviour varies depending on the snapshot values:
 *
 * - **Both PuckData** -- uses `diffPuckDataWithPositions` to compute
 *   component-level diffs (target as baseline, source as changed state).
 * - **Source has data, target is null** -- produces synthetic diffs
 *   where all source components are marked as `added` (new document).
 * - **Target has data, source is null** -- produces synthetic diffs
 *   where all target components are marked as `removed` (deleted document).
 * - **Neither is PuckData / both null** -- returns empty diffs with
 *   `isPuckData: false`.
 *
 * @param documentId   - Unique identifier of the document.
 * @param documentPath - Path of the document (e.g., '/pages/home').
 * @param sourceSnapshot - Snapshot from the source branch (or null).
 * @param targetSnapshot - Snapshot from the target branch (or null).
 * @returns A {@link BranchDocumentComparison} describing the differences.
 *
 * @example
 * ```typescript
 * const comparison = createBranchDocumentComparison(
 *   'doc-1',
 *   '/pages/home',
 *   sourceBranchSnapshot,
 *   targetBranchSnapshot
 * );
 * console.log(comparison.counts); // { added: 0, removed: 1, modified: 2, unchanged: 5 }
 * ```
 */
export declare function createBranchDocumentComparison(documentId: string, documentPath: string, sourceSnapshot: unknown, targetSnapshot: unknown): BranchDocumentComparison;
/**
 * Creates an aggregated comparison across multiple documents for a
 * branch merge operation.
 *
 * Calls {@link createBranchDocumentComparison} for each document and
 * aggregates the resulting counts. A document is considered "changed"
 * when it contains at least one diff whose type is **not** `unchanged`.
 *
 * @param documents - Array of document diff summaries to compare.
 * @returns A {@link BranchMergeComparison} with per-document results
 *          and aggregate statistics.
 *
 * @example
 * ```typescript
 * const merge = createBranchMergeComparison([
 *   { documentId: 'doc-1', documentPath: '/home', sourceSnapshot, targetSnapshot },
 *   { documentId: 'doc-2', documentPath: '/about', sourceSnapshot: null, targetSnapshot },
 * ]);
 * console.log(merge.changedDocumentCount); // number of docs with changes
 * ```
 */
export declare function createBranchMergeComparison(documents: DocumentDiffSummary[]): BranchMergeComparison;