(** The config file: what the user wants by default, and where each value came
    from.

    Owns precedence and provenance and nothing else. Never reads the filesystem
    -- callers hand it text -- so it is as testable as the language table.

    A config file is OPTIONAL. With none, colitur behaves exactly as it does
    without this feature, except that names resolve through the default
    language. *)

type t

val empty : t
val of_string : string -> (t, string) result

(** [lang], [template] and [format] are each set from a single field. A
    repeated key is LAST-WINS -- the opposite direction from
    {!Colitur_kernel.Overlay_ini.get}'s first-wins over the same [section]
    type -- because the natural reading of a config file a user edited by
    hand and appended to is "the bottom line is the one that took effect".
    This holds whether the repeat is within one [\[defaults\]] block or
    across two of them: every section named [defaults] is merged, not only
    the first, the same duplicate-section policy {!Lang.of_string} documents
    for its own sections -- the two modules read the same underlying format
    and must not disagree about what a repeated header means. *)
val lang : t -> string option

val overlays : t -> string list
val template : t -> string option
val format : t -> string option

(** Keys present in the [\[defaults\]] section that this build does not
    understand. Reported, never fatal: a config written for a newer colitur
    must still work on an older one, but silently ignoring a line the user
    wrote is how a typo becomes invisible. *)
val unknown_keys : t -> string list

(** Section names other than [\[defaults\]], reported separately from
    {!unknown_keys} so the CLI can word the two warnings differently (a
    misspelled section, e.g. [\[deafults\]], versus a misspelled key inside a
    recognised one). Also never fatal, and never silent: a section this build
    does not recognise is exactly the highest-value typo this feature exists
    to catch, because it silently discards the whole section -- [lang] and
    everything else in it -- with no other way for the user to notice. *)
val unknown_sections : t -> string list

(** [resolve ~flag ~config ~default] returns [(value, source)] with source one of
    ["flag"], ["config"], ["default"]. Precedence is flag > config > default. *)
val resolve : flag:string option -> config:string option -> default:string -> string * string