(** Tree and commit diff operations.

    This module provides functionality to compare trees and commits, producing a
    list of changes between them. *)

(** {1 Types} *)

(** A single change in a diff. *)
type change =
  | Added of { path : string; hash : Hash.t; perm : Tree.perm }
      (** File or directory added *)
  | Removed of { path : string; hash : Hash.t; perm : Tree.perm }
      (** File or directory removed *)
  | Modified of {
      path : string;
      old_hash : Hash.t;
      new_hash : Hash.t;
      old_perm : Tree.perm;
      new_perm : Tree.perm;
    }  (** File content changed (and optionally permissions) *)

type t = change list
(** A diff is a list of changes. *)

(** {1 Diff Operations} *)

val trees :
  Repository.t ->
  old_tree:Hash.t ->
  new_tree:Hash.t ->
  (t, [ `Msg of string ]) result
(** [trees repo ~old_tree ~new_tree] computes the difference between two trees.

    Returns a list of changes needed to transform [old_tree] into [new_tree].
    The changes are returned in lexicographical order by path. *)

val commits :
  Repository.t ->
  old_commit:Hash.t ->
  new_commit:Hash.t ->
  (t, [ `Msg of string ]) result
(** [commits repo ~old_commit ~new_commit] computes the difference between two
    commits by comparing their trees. *)

val tree_to_empty : Repository.t -> Hash.t -> (t, [ `Msg of string ]) result
(** [tree_to_empty repo tree] returns all entries in the tree as [Added]
    changes. Useful for showing the initial commit. *)

val empty_to_tree : Repository.t -> Hash.t -> (t, [ `Msg of string ]) result
(** [empty_to_tree repo tree] returns all entries in the tree as [Removed]
    changes. *)

(** {1 Filtering} *)

val filter_by_path : prefix:string -> t -> t
(** [filter_by_path ~prefix diff] returns only changes under the given path
    prefix. *)

(** {1 Statistics} *)

type stats = {
  additions : int;  (** Number of files added *)
  deletions : int;  (** Number of files removed *)
  modifications : int;  (** Number of files modified *)
}
(** Summary statistics for a diff. *)

val stats : t -> stats
(** [stats diff] computes summary statistics for the diff. *)

(** {1 Pretty Printing} *)

val pp_change : change Fmt.t
(** [pp_change] formats a single change. *)

val pp : t Fmt.t
(** [pp] formats a diff as a list of changes. *)

val pp_stats : stats Fmt.t
(** [pp_stats] formats diff statistics. *)