Monorepo management for opam overlays
fix(lint): resolve E410 doc style issues, E400/E405/E600 across kdf, monopam, ocaml-agent, ocaml-aos
E410: Fix documentation style in 14 .mli files — add [name args] format,
correct function names (create→v, scrypt_kdf→scrypt), fix arg counts
for tuple params and pp functions, add trailing periods.
E400/E600: Add per-module log sources (ca-certs), restructure kdf and
monopam tests to use suite convention with proper .mli files, add
missing .mli files for monopam command modules.
+374
-17
+11
lib/add.mli
+11
lib/add.mli
···
1
+
(** Add a package to the monorepo. *)
2
+
3
+
val add :
4
+
proc:_ Eio.Process.mgr ->
5
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
6
+
config:Config.t ->
7
+
package:string ->
8
+
unit ->
9
+
(unit, Ctx.error) result
10
+
(** [add ~proc ~fs ~config ~package ()] looks up the package in the opam repo,
11
+
ensures its checkout exists, and pulls the subtree into the monorepo. *)
+4
-3
lib/changes.mli
+4
-3
lib/changes.mli
···
141
141
(** {1 Date Calculation} *)
142
142
143
143
val format_date : int * int * int -> string
144
-
(** [format_date (year, month, day)] formats a date as YYYY-MM-DD. *)
144
+
(** [format_date date] formats a [(year, month, day)] triple as YYYY-MM-DD. *)
145
145
146
146
val week_of_date : int * int * int -> string * string
147
-
(** [week_of_date (year, month, day)] returns (week_start, week_end) as ISO date
148
-
strings. week_start is Monday, week_end is Sunday. *)
147
+
(** [week_of_date date] returns [(week_start, week_end)] as ISO date strings for
148
+
a [(year, month, day)] triple. [week_start] is Monday, [week_end] is Sunday.
149
+
*)
149
150
150
151
val week_of_ptime : Ptime.t -> string * string
151
152
(** [week_of_ptime t] returns (week_start, week_end) for the given timestamp. *)
+2
-2
lib/changes_aggregated.mli
+2
-2
lib/changes_aggregated.mli
···
75
75
76
76
val load :
77
77
fs:_ Eio.Path.t -> changes_dir:Fpath.t -> date:string -> (t, string) result
78
-
(** Load aggregated changes for a specific date. [date] should be in YYYY-MM-DD
79
-
format. *)
78
+
(** [load ~fs ~changes_dir ~date] loads aggregated changes for a specific date.
79
+
[date] should be in YYYY-MM-DD format. *)
80
80
81
81
val load_range :
82
82
fs:_ Eio.Path.t ->
+9
-6
lib/changes_query.mli
+9
-6
lib/changes_query.mli
···
16
16
since:Ptime.t ->
17
17
now:Ptime.t ->
18
18
(Changes_aggregated.entry list, string) result
19
-
(** Get all change entries from aggregated files created after [since]. Returns
20
-
entries from all days after the timestamp.
19
+
(** [changes_since ~fs ~changes_dir ~since ~now] returns all change entries from
20
+
aggregated files created after [since]. Returns entries from all days after
21
+
the timestamp.
21
22
@param now Current time for determining the date range end. *)
22
23
23
24
val has_new_changes :
···
32
33
include_date:bool ->
33
34
date:string option ->
34
35
string
35
-
(** Format entries as markdown suitable for Zulip. If [include_date] is true,
36
-
includes a date header. [date] is used for the header if provided. *)
36
+
(** [format_for_zulip ~entries ~include_date ~date] formats entries as markdown
37
+
suitable for Zulip. If [include_date] is true, includes a date header.
38
+
[date] is used for the header if provided. *)
37
39
38
40
val format_summary : entries:Changes_aggregated.entry list -> string
39
41
(** Format a brief summary of the changes. *)
···
45
47
changes_dir:Fpath.t ->
46
48
since:Ptime.t ->
47
49
Changes_daily.entry list
48
-
(** Get all daily change entries created after [since] timestamp. Uses the
49
-
per-day-per-repo files for real-time access. *)
50
+
(** [daily_changes_since ~fs ~changes_dir ~since] returns all daily change
51
+
entries created after [since] timestamp. Uses the per-day-per-repo files for
52
+
real-time access. *)
50
53
51
54
val has_new_daily_changes :
52
55
fs:_ Eio.Path.t -> changes_dir:Fpath.t -> since:Ptime.t -> bool
+12
lib/clean.mli
+12
lib/clean.mli
···
1
+
(** Clean empty commits from monorepo and checkouts. *)
2
+
3
+
val clean :
4
+
proc:_ Eio.Process.mgr ->
5
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
6
+
config:Config.t ->
7
+
dry_run:bool ->
8
+
force:bool ->
9
+
unit ->
10
+
(unit, Ctx.error) result
11
+
(** [clean ~proc ~fs ~config ~dry_run ~force ()] removes empty commits and
12
+
unrelated merge commits from git history. *)
+1
-2
lib/config.mli
+1
-2
lib/config.mli
···
130
130
?paths:paths ->
131
131
unit ->
132
132
t
133
-
(** [create ~root ~handle ?knot ?packages ?paths ()] creates a new
134
-
configuration.
133
+
(** [v ~root ~handle ?knot ?packages ?paths ()] creates a new configuration.
135
134
136
135
@param root Workspace root directory (absolute path).
137
136
@param handle User's handle.
+112
lib/ctx.mli
+112
lib/ctx.mli
···
1
+
(** Operational context for monopam commands.
2
+
3
+
Provides filesystem utilities, package discovery, checkout management, and
4
+
repository grouping functions shared across command modules. *)
5
+
6
+
(** {1 Error Types} *)
7
+
8
+
type error =
9
+
| Config_error of string
10
+
| Repo_error of Opam_repo.error
11
+
| Git_error of Git_cli.error
12
+
| Dirty_state of Package.t list
13
+
| Monorepo_dirty
14
+
| Package_not_found of string
15
+
| Claude_error of string
16
+
17
+
val pp_error : error Fmt.t
18
+
(** [pp_error] pretty-prints an error. *)
19
+
20
+
val error_hint : error -> string option
21
+
(** [error_hint e] returns a remediation hint for [e], if any. *)
22
+
23
+
val pp_error_with_hint : Format.formatter -> error -> unit
24
+
(** [pp_error_with_hint] pretty-prints an error with a remediation hint. *)
25
+
26
+
(** {1 Filesystem Utilities} *)
27
+
28
+
val fs_typed : Eio.Fs.dir_ty Eio.Path.t -> Eio.Fs.dir_ty Eio.Path.t
29
+
(** [fs_typed fs] coerces [fs] to a typed filesystem path. *)
30
+
31
+
val mkdirs : _ Eio.Path.t -> unit
32
+
(** [mkdirs path] recursively creates directories. *)
33
+
34
+
val is_directory : fs:Eio.Fs.dir_ty Eio.Path.t -> Fpath.t -> bool
35
+
(** [is_directory ~fs path] returns [true] if [path] is a directory. *)
36
+
37
+
val ensure_checkouts_dir :
38
+
fs:Eio.Fs.dir_ty Eio.Path.t -> config:Config.t -> unit
39
+
(** [ensure_checkouts_dir ~fs ~config] creates the checkouts directory. *)
40
+
41
+
(** {1 Package Discovery} *)
42
+
43
+
val discover_packages :
44
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
45
+
config:Config.t ->
46
+
unit ->
47
+
(Package.t list, error) result
48
+
(** [discover_packages ~fs ~config ()] scans the monorepo for packages. *)
49
+
50
+
val package :
51
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
52
+
config:Config.t ->
53
+
string ->
54
+
(Package.t, error) result
55
+
(** [package ~fs ~config name] looks up a single package by name. *)
56
+
57
+
(** {1 Branch and Checkout Management} *)
58
+
59
+
val branch : config:Config.t -> Package.t -> string
60
+
(** [branch ~config pkg] returns the branch name for [pkg]. *)
61
+
62
+
val ensure_checkout :
63
+
proc:_ Eio.Process.mgr ->
64
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
65
+
config:Config.t ->
66
+
Package.t ->
67
+
(unit, Git_cli.error) result
68
+
(** [ensure_checkout ~proc ~fs ~config pkg] clones or fetches the checkout. *)
69
+
70
+
val checkout_exists :
71
+
fs:Eio.Fs.dir_ty Eio.Path.t -> config:Config.t -> Package.t -> bool
72
+
(** [checkout_exists ~fs ~config pkg] returns [true] if the checkout exists. *)
73
+
74
+
val behind : fs:Eio.Fs.dir_ty Eio.Path.t -> config:Config.t -> Package.t -> int
75
+
(** [behind ~fs ~config pkg] returns the number of commits behind upstream. *)
76
+
77
+
(** {1 Repository Grouping} *)
78
+
79
+
val group_by_repo : Package.t list -> (string * Package.t list) list
80
+
(** [group_by_repo pkgs] groups packages by repository name. *)
81
+
82
+
val unique_repos : Package.t list -> Package.t list
83
+
(** [unique_repos pkgs] deduplicates packages by repository URL. *)
84
+
85
+
(** {1 URL Utilities} *)
86
+
87
+
val url_to_push_url : ?knot:string -> Uri.t -> string
88
+
(** [url_to_push_url ~knot uri] converts a dev-repo URL to a push URL. *)
89
+
90
+
(** {1 Unregistered Package Detection} *)
91
+
92
+
val unregistered_opam_files :
93
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
94
+
config:Config.t ->
95
+
Package.t list ->
96
+
(string * string) list
97
+
(** [unregistered_opam_files ~fs ~config pkgs] returns opam files not tracked by
98
+
any known package. *)
99
+
100
+
(** {1 Status} *)
101
+
102
+
val status :
103
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
104
+
config:Config.t ->
105
+
unit ->
106
+
(Status.t list, error) result
107
+
(** [status ~fs ~config ()] computes sync status for all packages. *)
108
+
109
+
(** {1 Timing} *)
110
+
111
+
val time_phase : string -> (unit -> 'a) -> 'a
112
+
(** [time_phase name f] runs [f] and logs the elapsed time. *)
+114
lib/diff.mli
+114
lib/diff.mli
···
1
+
(** Verse collaboration diff operations.
2
+
3
+
Compares local repositories with verse member forks to identify commits that
4
+
can be pulled or cherry-picked. *)
5
+
6
+
(** {1 Types} *)
7
+
8
+
type entry = {
9
+
repo_name : string;
10
+
handle : string;
11
+
relationship : Forks.relationship;
12
+
commits : Git.Repository.log_entry list;
13
+
patches : (string * string) list;
14
+
}
15
+
(** A diff entry for a single repo/handle pair. *)
16
+
17
+
type result = { entries : entry list; forks : Forks.t }
18
+
(** Diff result containing entries and fork analysis. *)
19
+
20
+
type commit_info = {
21
+
commit_repo : string;
22
+
commit_handle : string;
23
+
commit_hash : string;
24
+
commit_subject : string;
25
+
commit_author : string;
26
+
commit_patch : string;
27
+
}
28
+
(** Detailed information about a single commit. *)
29
+
30
+
type handle_pull_result = {
31
+
repos_pulled : (string * int) list;
32
+
repos_skipped : string list;
33
+
repos_failed : (string * string) list;
34
+
}
35
+
(** Result of pulling from a handle. *)
36
+
37
+
type cherrypick_result = {
38
+
repo_name : string;
39
+
commit_hash : string;
40
+
commit_subject : string;
41
+
}
42
+
(** Result of cherry-picking a commit. *)
43
+
44
+
(** {1 Pretty Printers} *)
45
+
46
+
val pp : show_patch:bool -> Format.formatter -> result -> unit
47
+
(** [pp ~show_patch ppf result] pretty-prints a diff result. *)
48
+
49
+
val pp_handle_pull_result : Format.formatter -> handle_pull_result -> unit
50
+
(** [pp_handle_pull_result] pretty-prints a handle pull result. *)
51
+
52
+
val pp_cherrypick_result : Format.formatter -> cherrypick_result -> unit
53
+
(** [pp_cherrypick_result] pretty-prints a cherry-pick result. *)
54
+
55
+
(** {1 Utilities} *)
56
+
57
+
val is_commit_sha : string -> bool
58
+
(** [is_commit_sha s] returns [true] if [s] looks like a git commit SHA. *)
59
+
60
+
(** {1 Diff Operations} *)
61
+
62
+
val diff :
63
+
proc:_ Eio.Process.mgr ->
64
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
65
+
config:Config.t ->
66
+
verse_config:Verse_config.t ->
67
+
?repo:string ->
68
+
?refresh:bool ->
69
+
?patch:bool ->
70
+
unit ->
71
+
result
72
+
(** [diff ~proc ~fs ~config ~verse_config ()] computes the diff between local
73
+
and verse state. *)
74
+
75
+
val show_commit :
76
+
proc:_ Eio.Process.mgr ->
77
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
78
+
config:Config.t ->
79
+
verse_config:Verse_config.t ->
80
+
sha:string ->
81
+
?refresh:bool ->
82
+
unit ->
83
+
commit_info option
84
+
(** [show_commit ~proc ~fs ~config ~verse_config ~sha ()] shows details for a
85
+
specific commit in the verse diff. *)
86
+
87
+
(** {1 Pull from Handle} *)
88
+
89
+
val pull_from_handle :
90
+
proc:_ Eio.Process.mgr ->
91
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
92
+
config:Config.t ->
93
+
verse_config:Verse_config.t ->
94
+
handle:string ->
95
+
?repo:string ->
96
+
?refresh:bool ->
97
+
unit ->
98
+
(handle_pull_result, Ctx.error) Stdlib.result
99
+
(** [pull_from_handle ~proc ~fs ~config ~verse_config ~handle ()] pulls changes
100
+
from a verse collaborator's handle. *)
101
+
102
+
(** {1 Cherry-pick} *)
103
+
104
+
val cherrypick :
105
+
proc:_ Eio.Process.mgr ->
106
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
107
+
config:Config.t ->
108
+
verse_config:Verse_config.t ->
109
+
sha:string ->
110
+
?refresh:bool ->
111
+
unit ->
112
+
(cherrypick_result, Ctx.error) Stdlib.result
113
+
(** [cherrypick ~proc ~fs ~config ~verse_config ~sha ()] cherry-picks a commit
114
+
from the verse diff. *)
+35
lib/init.mli
+35
lib/init.mli
···
1
+
(** Monorepo initialization and file generation.
2
+
3
+
Handles creating and updating the monorepo git repository, README.md,
4
+
CLAUDE.md, .gitignore, and dune-project files. *)
5
+
6
+
val ensure :
7
+
proc:_ Eio.Process.mgr ->
8
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
9
+
config:Config.t ->
10
+
(unit, Ctx.error) result
11
+
(** [ensure ~proc ~fs ~config] initializes the monorepo if needed. *)
12
+
13
+
val write_readme :
14
+
proc:_ Eio.Process.mgr ->
15
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
16
+
config:Config.t ->
17
+
Package.t list ->
18
+
unit
19
+
(** [write_readme ~proc ~fs ~config pkgs] updates README.md if changed. *)
20
+
21
+
val write_claude_md :
22
+
proc:_ Eio.Process.mgr ->
23
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
24
+
config:Config.t ->
25
+
unit
26
+
(** [write_claude_md ~proc ~fs ~config] updates CLAUDE.md if changed. *)
27
+
28
+
val write_dune_project :
29
+
proc:_ Eio.Process.mgr ->
30
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
31
+
config:Config.t ->
32
+
Package.t list ->
33
+
unit
34
+
(** [write_dune_project ~proc ~fs ~config pkgs] updates dune-project if changed.
35
+
*)
+1
-1
lib/mono_lock.mli
+1
-1
lib/mono_lock.mli
···
38
38
(** [names t] returns the list of package names. *)
39
39
40
40
val lock_filename : string
41
-
(** Default filename: "mono.lock" *)
41
+
(** [lock_filename] is the default filename: ["mono.lock"]. *)
42
42
43
43
val load : fs:Eio.Fs.dir_ty Eio.Path.t -> Fpath.t -> (t, string) result
44
44
(** [load ~fs path] reads a lock file from [path]. *)
+1
-1
lib/monopam.mli
+1
-1
lib/monopam.mli
···
101
101
(** [pp_cherrypick_result] pretty-prints a cherry-pick result. *)
102
102
103
103
val pp_diff_result : show_patch:bool -> Format.formatter -> Diff.result -> unit
104
-
(** [pp_diff_result ~show_patch] pretty-prints a diff result. *)
104
+
(** [pp_diff_result ~show_patch ppf result] pretty-prints a diff result. *)
105
105
106
106
val pull_from_handle :
107
107
proc:_ Eio.Process.mgr ->
+2
-2
lib/package.mli
+2
-2
lib/package.mli
···
20
20
?synopsis:string ->
21
21
unit ->
22
22
t
23
-
(** [create ~name ~version ~dev_repo ?branch ?depends ?synopsis ()] creates a
24
-
new package.
23
+
(** [v ~name ~version ~dev_repo ?branch ?depends ?synopsis ()] creates a new
24
+
package.
25
25
26
26
@param name The opam package name.
27
27
@param version The package version (e.g., ["dev"]).
+28
lib/pull.mli
+28
lib/pull.mli
···
1
+
(** Pull operations for syncing upstream changes to the monorepo. *)
2
+
3
+
type result = {
4
+
repo_name : string;
5
+
cloned : bool;
6
+
commits_pulled : int;
7
+
subtree_added : bool;
8
+
}
9
+
(** Result of a pull operation for a single repository. *)
10
+
11
+
val subtree :
12
+
proc:_ Eio.Process.mgr ->
13
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
14
+
config:Config.t ->
15
+
Package.t ->
16
+
(bool, Ctx.error) Stdlib.result
17
+
(** [subtree ~proc ~fs ~config pkg] merges or adds the subtree for [pkg].
18
+
Returns [true] if the subtree was newly added. *)
19
+
20
+
val pull :
21
+
proc:_ Eio.Process.mgr ->
22
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
23
+
config:Config.t ->
24
+
?packages:string list ->
25
+
?opam_repo_url:string ->
26
+
unit ->
27
+
(unit, Ctx.error) Stdlib.result
28
+
(** [pull ~proc ~fs ~config ()] fetches checkouts and merges subtrees. *)
+14
lib/push.mli
+14
lib/push.mli
···
1
+
(** Push operations for exporting monorepo changes to checkouts and upstream. *)
2
+
3
+
val push :
4
+
proc:_ Eio.Process.mgr ->
5
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
6
+
config:Config.t ->
7
+
?packages:string list ->
8
+
?upstream:bool ->
9
+
?clean:bool ->
10
+
?force:bool ->
11
+
unit ->
12
+
(unit, Ctx.error) result
13
+
(** [push ~proc ~fs ~config ()] exports changes via subtree split and pushes to
14
+
local checkouts and optionally to remote upstreams. *)
+10
lib/remove.mli
+10
lib/remove.mli
···
1
+
(** Remove a package subtree from the monorepo. *)
2
+
3
+
val remove :
4
+
fs:Eio.Fs.dir_ty Eio.Path.t ->
5
+
config:Config.t ->
6
+
package:string ->
7
+
unit ->
8
+
(unit, Ctx.error) result
9
+
(** [remove ~fs ~config ~package ()] deletes the subtree directory from the
10
+
monorepo. Does not affect the opam overlay or upstream repository. *)
+4
test/test.ml
+4
test/test.ml
+2
test/test_monopam.mli
+2
test/test_monopam.mli
+1
test/test_progress.ml
+1
test/test_progress.ml
···
1
+
let suite = ("progress", [])
+2
test/test_progress.mli
+2
test/test_progress.mli
+1
test/test_pull.ml
+1
test/test_pull.ml
···
1
+
let suite = ("pull", [])
+2
test/test_pull.mli
+2
test/test_pull.mli
+1
test/test_push.ml
+1
test/test_push.ml
···
1
+
let suite = ("push", [])
+2
test/test_push.mli
+2
test/test_push.mli
+1
test/test_remove.ml
+1
test/test_remove.ml
···
1
+
let suite = ("remove", [])