(** Reading and validating the TOML configuration.

    The file is looked up at [$OGIT_CONFIG], then
    [$XDG_CONFIG_HOME/ogit/config.toml], then [/etc/ogit/config.toml]. When no
    file is chosen explicitly a missing one is fine and {!default} applies; a
    file that exists but is malformed or invalid is always an error, so a
    mistake never silently degrades into defaults.

    {!to_table} and {!write_file} support the [ogit-write-config] executable,
    which emits a config file pre-filled with the defaults. *)

(** {1 Configuration record} *)

type t = {
  user_name : string;
  default_branch : string;
  git_project_root : string;
  commits_max_displayed : int;
  root_title : string;
  nav_logo : string;
  host : string;
  port : int;
  favorite_repositories : string list;
  archived_repositories : string list;
}
(** All settings that influence the server's behaviour. *)

(** {1 Errors} *)

type load_error =
  | Not_found of string
  | Parse_error of string
  | Invalid_value of string
  | Io_error of string

val pp_load_error : Format.formatter -> load_error -> unit
(** Format a load error for diagnostics. *)

val show_load_error : load_error -> string
(** Render a load error as a string. *)

(** {1 Defaults} *)

val default : t
(** The configuration used when no file is found. *)

(** {1 Loading} *)

val load : unit -> (t, load_error) result
(** Locate and parse the configuration file, or return {!default} when no
    implicit file exists. An explicit [$OGIT_CONFIG] that is missing or
    malformed is always an error. *)

val read_file : ?file:string -> unit -> (t, load_error) result
(** Parse a specific configuration file. *)

(** {1 Serialisation} *)

val to_table : t -> Toml.Types.table
(** Convert a configuration record to a TOML table, suitable for writing back to
    disk. *)

val write_file : ?file:string -> Toml.Types.table -> unit
(** Write a TOML table to the given file, or to the default configuration path.
*)

(** {1 Internals exposed for tooling} *)

val locate_config_file : unit -> string
(** Return the path that would be used for the configuration file, following the
    [$OGIT_CONFIG] then [$XDG_CONFIG_HOME] then [/etc] resolution order. Useful
    for diagnostic tools. *)