From d22c06a001f62efd71a8989c3cd6f35cbda8c4be Mon Sep 17 00:00:00 2001
From: Mathieu Barbin <mathieu.barbin@gmail.com>
Date: Tue, 30 Jul 2024 09:00:04 +0200
Subject: [PATCH] Add an admin command to compare 2 package versions

This is meant for quick sanity checks for example.

- Added some basic tests to cover the command. The tests I added do
  not duplicate the tests for the actual comparison function, rather
  that meant to cover the basic cases encountered by the command.

Signed-off-by: Mathieu Barbin <mathieu.barbin@gmail.com>
---
 doc/man/opam-admin-topics.inc                | 11 +++++++
 master_changes.md                            |  1 +
 src/client/opamAdminCommand.ml               | 34 ++++++++++++++++++++
 tests/reftests/compare-package-versions.test |  7 ++++
 tests/reftests/dune.inc                      | 18 +++++++++++
 5 files changed, 71 insertions(+)
 create mode 100644 tests/reftests/compare-package-versions.test

diff --git a/doc/man/opam-admin-topics.inc b/doc/man/opam-admin-topics.inc
index c2618ecb6cf..1e5cdc95fb0 100644
--- a/doc/man/opam-admin-topics.inc
+++ b/doc/man/opam-admin-topics.inc
@@ -60,6 +60,16 @@
                  (diff opam-admin-list.err %{dep:opam-admin-list.0})))
   (package opam))
 
+(rule
+  (with-stdout-to opam-admin-compare-package-versions.0 (echo "")))
+(rule
+  (targets opam-admin-compare-package-versions.1 opam-admin-compare-package-versions.err)
+  (deps using-built-opam)
+  (action (progn (with-stderr-to opam-admin-compare-package-versions.err
+                   (with-stdout-to opam-admin-compare-package-versions.1 (run %{bin:opam} admin compare-package-versions --help=groff)))
+                 (diff opam-admin-compare-package-versions.err %{dep:opam-admin-compare-package-versions.0})))
+  (package opam))
+
 (rule
   (with-stdout-to opam-admin-check.0 (echo "")))
 (rule
@@ -130,6 +140,7 @@
     opam-admin-add-constraint.1 
     opam-admin-filter.1 
     opam-admin-list.1 
+    opam-admin-compare-package-versions.1 
     opam-admin-check.1 
     opam-admin-lint.1 
     opam-admin-upgrade.1 
diff --git a/master_changes.md b/master_changes.md
index a5b83d282b3..3105abb59df 100644
--- a/master_changes.md
+++ b/master_changes.md
@@ -15,6 +15,7 @@ users)
   * Bump opam-root-version to 2.2 [#5980 @kit-ty-kate]
 
 ## Global CLI
+  * ◈ Add `opam admin compare-package-versions` to compare package versions for sanity checks [#<PR_NUMBER> @mbarbin]
   * Add cli version 2.3 [#6045 @rjbou]
 
 ## Plugins
diff --git a/src/client/opamAdminCommand.ml b/src/client/opamAdminCommand.ml
index 9714372eed6..94fe580e849 100644
--- a/src/client/opamAdminCommand.ml
+++ b/src/client/opamAdminCommand.ml
@@ -830,6 +830,39 @@ let check_command cli =
   Term.(const cmd $ global_options cli $ ignore_test_arg $ print_short_arg
         $ installability_arg $ cycles_arg $ obsolete_arg)
 
+let compare_package_versions_command_doc = "Compare 2 package versions"
+let compare_package_versions_command cli =
+  let version_arg n =
+    let doc =
+      Arg.info
+        ~docv:"VERSION"
+        ~doc:"Package version to compare" []
+    in
+    Arg.(required & pos n (Arg.some' OpamArg.package_version) None & doc)
+  in
+  let command = "compare-package-versions" in
+  let doc = compare_package_versions_command_doc in
+  let man = [
+    `S Manpage.s_description;
+    `P "This command compares 2 package versions for quick sanity checks, and prints the result of the comparison to the console. For example:";
+    `I ("For example:", "opam admin compare-package-versions 0.0.9 0.0.10");
+    `I ("outputs:", "-1 (0.0.9 < 0.0.10)");
+    `S Manpage.s_arguments;
+    `S Manpage.s_options;
+  ]
+  in
+  let cmd global_options v1 v2 () =
+    OpamArg.apply_global_options cli global_options;
+    let result = OpamPackage.Version.compare v1 v2 in
+    OpamConsole.formatted_msg "%d (%s %s %s)\n"
+      result
+      (OpamPackage.Version.to_string v1)
+      (if result < 0 then "<" else if result = 0 then "=" else ">")
+      (OpamPackage.Version.to_string v2);
+  in
+  OpamArg.mk_command  ~cli OpamArg.cli_original command ~doc ~man
+  Term.(const cmd $ global_options cli $ version_arg 0 $ version_arg 1)
+
 let pattern_list_arg =
   OpamArg.arg_list "PATTERNS"
     "Package patterns with globs. matching against $(b,NAME) or \
@@ -1217,6 +1250,7 @@ let admin_subcommands cli =
     upgrade_command cli;
     lint_command cli;
     check_command cli;
+    compare_package_versions_command cli;
     list_command cli;
     filter_command cli;
     add_constraint_command cli;
diff --git a/tests/reftests/compare-package-versions.test b/tests/reftests/compare-package-versions.test
new file mode 100644
index 00000000000..22233ca08f7
--- /dev/null
+++ b/tests/reftests/compare-package-versions.test
@@ -0,0 +1,7 @@
+N0REP0
+### opam admin compare-package-versions 0.0.9 0.0.10
+-1 (0.0.9 < 0.0.10)
+### opam admin compare-package-versions 1.2.3 1.2.3~preview
+1 (1.2.3 > 1.2.3~preview)
+### opam admin compare-package-versions 0.1.0 0.01.0
+0 (0.1.0 = 0.01.0)
diff --git a/tests/reftests/dune.inc b/tests/reftests/dune.inc
index cbb93c3364b..e71f05bf55e 100644
--- a/tests/reftests/dune.inc
+++ b/tests/reftests/dune.inc
@@ -161,6 +161,24 @@
    %{targets}
    (run ./run.exe %{exe:../../src/client/opamMain.exe.exe} %{dep:cli-versioning.test} %{read-lines:testing-env}))))
 
+(rule
+ (alias reftest-compare-package-versions)
+ (action
+  (diff compare-package-versions.test compare-package-versions.out)))
+
+(alias
+ (name reftest)
+ (deps (alias reftest-compare-package-versions)))
+
+(rule
+ (targets compare-package-versions.out)
+ (deps root-N0REP0)
+ (package opam)
+ (action
+  (with-stdout-to
+   %{targets}
+   (run ./run.exe %{exe:../../src/client/opamMain.exe.exe} %{dep:compare-package-versions.test} %{read-lines:testing-env}))))
+
 (rule
  (alias reftest-config)
  (action