From 36de1c6e512435dffe0f27e1c117bd725cfba293 Mon Sep 17 00:00:00 2001
From: Guillaume Nodet <gnodet@gmail.com>
Date: Thu, 12 Sep 2024 06:39:22 +0200
Subject: [PATCH] [MNG-8237] Option deprecation notices cleanup (#1713)

---
 .../java/org/apache/maven/cli/CLIManager.java | 60 +++++++++++++------
 .../java/org/apache/maven/cli/MavenCli.java   | 48 ++++++++++-----
 2 files changed, 76 insertions(+), 32 deletions(-)

diff --git a/maven-embedder/src/main/java/org/apache/maven/cli/CLIManager.java b/maven-embedder/src/main/java/org/apache/maven/cli/CLIManager.java
index 5e11454a62..7a6c3ea4e7 100644
--- a/maven-embedder/src/main/java/org/apache/maven/cli/CLIManager.java
+++ b/maven-embedder/src/main/java/org/apache/maven/cli/CLIManager.java
@@ -20,10 +20,12 @@ package org.apache.maven.cli;
 
 import java.io.PrintStream;
 import java.io.PrintWriter;
+import java.util.LinkedHashSet;
+import java.util.Set;
 
 import org.apache.commons.cli.CommandLine;
-import org.apache.commons.cli.CommandLineParser;
 import org.apache.commons.cli.DefaultParser;
+import org.apache.commons.cli.DeprecatedAttributes;
 import org.apache.commons.cli.HelpFormatter;
 import org.apache.commons.cli.Option;
 import org.apache.commons.cli.Options;
@@ -130,11 +132,12 @@ public class CLIManager {
     public static final String IGNORE_TRANSITIVE_REPOSITORIES = "itr";
 
     /** This option is deprecated and may be repurposed as Java debug in a future version.
-     * Use {@code -X/--verbose} instead. */
+     * Use {@code -X,--verbose} instead. */
     @Deprecated
     public static final String DEBUG = "debug";
 
     protected Options options;
+    protected final Set<Option> usedDeprecatedOptions = new LinkedHashSet<>();
 
     @SuppressWarnings("checkstyle:MethodLength")
     public CLIManager() {
@@ -223,12 +226,6 @@ public class CLIManager {
                 .desc("Alternate path for the project settings file")
                 .hasArg()
                 .build());
-        options.addOption(Option.builder(ALTERNATE_GLOBAL_SETTINGS)
-                .longOpt("global-settings")
-                .desc("Alternate path for the global settings file")
-                .hasArg()
-                .deprecated()
-                .build());
         options.addOption(Option.builder(ALTERNATE_INSTALLATION_SETTINGS)
                 .longOpt("install-settings")
                 .desc("Alternate path for the installation settings file")
@@ -239,12 +236,6 @@ public class CLIManager {
                 .desc("Alternate path for the user toolchains file")
                 .hasArg()
                 .build());
-        options.addOption(Option.builder(ALTERNATE_GLOBAL_TOOLCHAINS)
-                .longOpt("global-toolchains")
-                .desc("Alternate path for the global toolchains file")
-                .hasArg()
-                .deprecated()
-                .build());
         options.addOption(Option.builder(ALTERNATE_INSTALLATION_TOOLCHAINS)
                 .longOpt("install-toolchains")
                 .desc("Alternate path for the installation toolchains file")
@@ -351,13 +342,42 @@ public class CLIManager {
         // Adding this back to make Maven fail if used
         options.addOption(Option.builder("llr")
                 .longOpt("legacy-local-repository")
-                .desc("UNSUPPORTED: Use of this option will make Maven invocation fail.")
+                .desc("<deprecated> Use Maven 2 Legacy Local Repository behaviour.")
+                .deprecated(DeprecatedAttributes.builder()
+                        .setSince("3.9.1")
+                        .setDescription("UNSUPPORTED: Use of this option will make Maven invocation fail.")
+                        .get())
                 .build());
 
         // Deprecated
         options.addOption(Option.builder()
                 .longOpt(DEBUG)
-                .desc("Produce execution verbose output (deprecated; only kept for backward compatibility)")
+                .desc("<deprecated> Produce execution verbose output.")
+                .deprecated(DeprecatedAttributes.builder()
+                        .setForRemoval(true)
+                        .setSince("4.0.0")
+                        .setDescription("Use -X,--verbose instead.")
+                        .get())
+                .build());
+        options.addOption(Option.builder(ALTERNATE_GLOBAL_SETTINGS)
+                .longOpt("global-settings")
+                .desc("<deprecated> Alternate path for the global settings file.")
+                .hasArg()
+                .deprecated(DeprecatedAttributes.builder()
+                        .setForRemoval(true)
+                        .setSince("4.0.0")
+                        .setDescription("Use -is,--install-settings instead.")
+                        .get())
+                .build());
+        options.addOption(Option.builder(ALTERNATE_GLOBAL_TOOLCHAINS)
+                .longOpt("global-toolchains")
+                .desc("<deprecated> Alternate path for the global toolchains file.")
+                .hasArg()
+                .deprecated(DeprecatedAttributes.builder()
+                        .setForRemoval(true)
+                        .setSince("4.0.0")
+                        .setDescription("Use -it,--install-toolchains instead.")
+                        .get())
                 .build());
     }
 
@@ -365,11 +385,17 @@ public class CLIManager {
         // We need to eat any quotes surrounding arguments...
         String[] cleanArgs = CleanArgument.cleanArgs(args);
 
-        CommandLineParser parser = new DefaultParser();
+        DefaultParser parser = DefaultParser.builder()
+                .setDeprecatedHandler(usedDeprecatedOptions::add)
+                .build();
 
         return parser.parse(options, cleanArgs);
     }
 
+    public Set<Option> getUsedDeprecatedOptions() {
+        return usedDeprecatedOptions;
+    }
+
     public void displayHelp(PrintStream stdout) {
         stdout.println();
 
diff --git a/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java b/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java
index d4acfc0f7f..28d898c6ad 100644
--- a/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java
+++ b/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java
@@ -423,17 +423,6 @@ public class MavenCli {
             cliManager.displayHelp(System.out);
             throw e;
         }
-
-        // check for presence of unsupported command line options
-        try {
-            if (cliRequest.commandLine.hasOption("llr")) {
-                throw new UnrecognizedOptionException("Option '-llr' is not supported starting with Maven 3.9.1");
-            }
-        } catch (ParseException e) {
-            System.err.println("Unsupported options: " + e.getMessage());
-            cliManager.displayHelp(System.out);
-            throw e;
-        }
     }
 
     private void informativeCommands(CliRequest cliRequest) throws ExitException {
@@ -495,7 +484,7 @@ public class MavenCli {
     /**
      * configure logging
      */
-    void logging(CliRequest cliRequest) {
+    void logging(CliRequest cliRequest) throws ExitException {
         // LOG LEVEL
         CommandLine commandLine = cliRequest.commandLine;
         cliRequest.verbose = commandLine.hasOption(CLIManager.VERBOSE) || commandLine.hasOption(CLIManager.DEBUG);
@@ -572,9 +561,37 @@ public class MavenCli {
             }
         }
 
-        if (commandLine.hasOption(CLIManager.DEBUG)) {
-            slf4jLogger.warn("The option '--debug' is deprecated and may be repurposed as Java debug"
-                    + " in a future version. Use -X/--verbose instead.");
+        // check for presence of deprecated options and print warning
+        boolean fail = false;
+        for (Option option : cliRequest.commandLine.getOptions()) {
+            if (option.isDeprecated()) {
+                StringBuilder sb = new StringBuilder();
+                sb.append("The option -").append(option.getOpt());
+                if (option.getLongOpt() != null) {
+                    sb.append(",--").append(option.getLongOpt());
+                }
+                sb.append(" is deprecated ");
+                if (option.getDeprecated().isForRemoval()) {
+                    sb.append("and will be removed in a future version");
+                }
+                if (option.getDeprecated().getSince() != null) {
+                    sb.append("since Maven ").append(option.getDeprecated().getSince());
+                }
+                boolean error = false;
+                if (option.getDeprecated().getDescription() != null) {
+                    sb.append(": ").append(option.getDeprecated().getDescription());
+                    error = option.getDeprecated().getDescription().startsWith("UNSUPPORTED:");
+                }
+                if (error) {
+                    slf4jLogger.error(sb.toString());
+                    fail = true;
+                } else {
+                    slf4jLogger.warn(sb.toString());
+                }
+            }
+        }
+        if (fail) {
+            throw new ExitException(1);
         }
     }
 
@@ -632,6 +649,7 @@ public class MavenCli {
         BasicInterpolator interpolator =
                 createInterpolator(paths, cliRequest.systemProperties, cliRequest.userProperties);
         CommandLine.Builder commandLineBuilder = new CommandLine.Builder();
+        commandLineBuilder.setDeprecatedHandler(o -> {});
         for (Option option : cliRequest.commandLine.getOptions()) {
             if (!String.valueOf(CLIManager.SET_USER_PROPERTY).equals(option.getOpt())) {
                 List<String> values = option.getValuesList();