(** Shared helpers for precommit subcommands. *)

open Cmdliner

val success : ('a, Format.formatter, unit) format -> 'a
(** [success fmt] prints a success message. *)

val error : ('a, Format.formatter, unit) format -> 'a
(** [error fmt] prints an error message. *)

val info : ('a, Format.formatter, unit) format -> 'a
(** [info fmt] prints an informational message. *)

val plural : int -> string
(** [plural n] returns ["s"] unless [n] is one. *)

val setup : unit Term.t
(** [setup] configures common command-line options. *)

val chdir : string option Term.t
(** [chdir] is the optional working-directory argument. *)

val dirs : string list Term.t
(** [dirs] is the list of directories to inspect. *)

val dry_run : bool Term.t
(** [dry_run] is the flag for previewing changes. *)

val force : bool Term.t
(** [force] is the flag for forcing an operation. *)

val hooks : Precommit.hooks Term.t
(** [hooks] selects the pre-commit hooks to operate on. *)

val or_die : (unit, string) result -> unit
(** [or_die result] exits on [Error] and returns on [Ok]. *)

val collect_dirs : Precommit.ctx -> string list -> string list
(** [collect_dirs ctx dirs] expands command-line directories for [ctx]. *)

val with_env :
  string option -> (Precommit.ctx -> Eio_unix.Stdenv.base -> 'a) -> 'a
(** [with_env chdir f] builds a precommit context inside the command's Console
    scope and runs [f ctx env], with [env] the Eio environment the context was
    built from. *)

val with_ctx : string option -> (Precommit.ctx -> 'a) -> 'a
(** [with_ctx chdir f] is {!with_env} for a command that needs no environment
    beyond the context. *)

val display_ai_commits : Precommit.ctx -> string list -> string list * int * int
(** [display_ai_commits ctx dirs] prints the AI-attribution commit table and
    returns [(affected_dirs, total_commits, repos_with_issues)]. *)