jon.recoil.org
forked from
anil.recoil.org/monopam
Monorepo management for opam overlays
1(** Unified configuration for monopam.
2
3 Configuration is stored in TOML format at [~/.config/monopam/opamverse.toml].
4
5 The config stores:
6 - Workspace root and custom paths
7 - User identity (handle, knot)
8 - Per-package overrides
9
10 Standard paths derived from root:
11 - [mono/] - user's monorepo
12 - [src/] - git checkouts for subtrees
13 - [opam-repo/] - opam overlay repository
14 - [verse/] - other members' monorepos *)
15
16(** {1 Types} *)
17
18(** Per-package configuration overrides. *)
19module Package_config : sig
20 type t
21 (** Package-specific settings. *)
22
23 val branch : t -> string option
24 (** [branch t] returns the branch override for this package, if set. *)
25end
26
27(** Configurable paths within the workspace.
28
29 By default, paths are:
30 - [mono = "mono"] - monorepo directory
31 - [src = "src"] - source checkouts directory
32 - [verse = "verse"] - verse directory
33
34 Set [mono = "."] to have packages at the root level. *)
35type paths = {
36 mono : string; (** Monorepo directory (default: "mono") *)
37 src : string; (** Source checkouts directory (default: "src") *)
38 verse : string; (** Verse directory (default: "verse") *)
39}
40
41val default_paths : paths
42(** Default paths configuration. *)
43
44type t
45(** The main configuration. *)
46
47(** {1 Accessors} *)
48
49val root : t -> Fpath.t
50(** [root t] returns the workspace root directory. *)
51
52val handle : t -> string
53(** [handle t] returns the user's handle. *)
54
55val knot : t -> string
56(** [knot t] returns the git push server hostname (e.g., "git.recoil.org").
57 Used for converting tangled URLs to SSH push URLs. *)
58
59val paths : t -> paths
60(** [paths t] returns the paths configuration. *)
61
62val packages : t -> (string * Package_config.t) list
63(** [packages t] returns the list of package overrides. *)
64
65val package_config : t -> string -> Package_config.t option
66(** [package_config t name] returns package-specific configuration overrides for
67 the named package, if any exist. *)
68
69(** {1 Derived Paths} *)
70
71val default_branch : string
72(** Default git branch, always ["main"]. *)
73
74val mono_path : t -> Fpath.t
75(** [mono_path t] returns the path to the user's monorepo. *)
76
77val src_path : t -> Fpath.t
78(** [src_path t] returns the path to git checkouts. *)
79
80val opam_repo_path : t -> Fpath.t
81(** [opam_repo_path t] returns the path to the opam overlay. *)
82
83val verse_path : t -> Fpath.t
84(** [verse_path t] returns the path to tracked members' monorepos. *)
85
86(** {1 Backwards Compatibility} *)
87
88(** Path accessors using old naming convention. *)
89module Paths : sig
90 val opam_repo : t -> Fpath.t
91 (** Alias for [opam_repo_path]. *)
92
93 val checkouts : t -> Fpath.t
94 (** Alias for [src_path]. *)
95
96 val monorepo : t -> Fpath.t
97 (** Alias for [mono_path]. *)
98end
99
100(** {1 XDG Paths} *)
101
102val config_dir : unit -> Fpath.t
103(** [config_dir ()] returns the XDG config directory for monopam
104 (~/.config/monopam). *)
105
106val data_dir : unit -> Fpath.t
107(** [data_dir ()] returns the XDG data directory for monopam
108 (~/.local/share/monopam). *)
109
110val cache_dir : unit -> Fpath.t
111(** [cache_dir ()] returns the XDG cache directory for monopam
112 (~/.cache/monopam). *)
113
114val config_file : unit -> Fpath.t
115(** [config_file ()] returns the path to the config file
116 (~/.config/monopam/opamverse.toml). *)
117
118val registry_path : unit -> Fpath.t
119(** [registry_path ()] returns the path to the cloned registry git repo
120 (~/.local/share/monopam/opamverse-registry). *)
121
122(** {1 Construction} *)
123
124val create :
125 root:Fpath.t ->
126 handle:string ->
127 ?knot:string ->
128 ?packages:(string * Package_config.t) list ->
129 ?paths:paths ->
130 unit ->
131 t
132(** [create ~root ~handle ?knot ?packages ?paths ()] creates a new configuration.
133
134 @param root Workspace root directory (absolute path)
135 @param handle User's handle
136 @param knot Git push server hostname. If not provided, derived from handle
137 @param packages Optional list of package overrides
138 @param paths Optional custom paths configuration *)
139
140val with_package_override : t -> name:string -> ?branch:string -> unit -> t
141(** [with_package_override t ~name ?branch ()] returns a new config
142 with overrides for the named package. *)
143
144(** {1 Validation} *)
145
146type validation_error =
147 | Path_not_found of string * Fpath.t
148 | Not_a_directory of string * Fpath.t
149 | Not_an_opam_repo of Fpath.t
150 | Invalid_path of string * string
151 | Relative_path of string * Fpath.t
152
153val pp_validation_error : validation_error Fmt.t
154(** [pp_validation_error] formats validation errors. *)
155
156(** {1 Loading and Saving} *)
157
158val load : fs:_ Eio.Path.t -> unit -> (t, string) result
159(** [load ~fs ()] loads the configuration from the XDG config file.
160
161 @param fs Eio filesystem *)
162
163val save : fs:_ Eio.Path.t -> t -> (unit, string) result
164(** [save ~fs config] saves the configuration to the XDG config file.
165
166 @param fs Eio filesystem
167 @param config Configuration to save *)
168
169(** {1 Pretty Printing} *)
170
171val pp : t Fmt.t
172(** [pp] is a formatter for configuration. *)