Build Report Foundation — structured report, console modes, warning control

apache-maven/src/assembly/component.xml

@@ -87,6 +87,7 @@ under the License.
       <includes>
         <include>mvn</include>
         <include>mvnenc</include>
+        <include>mvnlog</include>
         <include>mvnsh</include>
         <include>mvnup</include>
         <include>mvnDebug</include>

apache-maven/src/assembly/maven/bin/mvn

@@ -303,6 +303,9 @@ handle_args() {
       --up)
         MAVEN_MAIN_CLASS="org.apache.maven.cling.MavenUpCling"
         ;;
+      --log)
+        MAVEN_MAIN_CLASS="org.apache.maven.cling.MavenLogCling"
+        ;;
       *)
         ;;
     esac
@@ -311,6 +314,21 @@ handle_args() {
 }
 
 handle_args "$@"
+
+# Strip routing flags (--debug, --yjp, --enc, --shell, --up, --log) from $@
+# so they are not passed to the Java process where they may collide with
+# Commons CLI option-prefix matching (e.g. --log matches --log-file).
+_argc=$#
+_i=0
+while [ $_i -lt $_argc ]; do
+  _arg="$1"
+  shift
+  case $_arg in
+    --debug|--yjp|--enc|--shell|--up|--log) ;;
+    *) set -- "$@" "$_arg" ;;
+  esac
+  _i=$((_i + 1))
+done
 MAVEN_MAIN_CLASS=${MAVEN_MAIN_CLASS:=org.apache.maven.cling.MavenCling}
 
 # Build base command string for eval (only contains Maven-controlled values)

apache-maven/src/assembly/maven/bin/mvn.cmd

@@ -275,6 +275,8 @@ if "%~1"=="--debug" (
       set "MAVEN_MAIN_CLASS=org.apache.maven.cling.MavenShellCling"
 ) else if "%~1"=="--up" (
       set "MAVEN_MAIN_CLASS=org.apache.maven.cling.MavenUpCling"
+) else if "%~1"=="--log" (
+      set "MAVEN_MAIN_CLASS=org.apache.maven.cling.MavenLogCling"
 )
 exit /b 0
 

apache-maven/src/assembly/maven/bin/mvnlog

@@ -0,0 +1,30 @@
+#!/bin/sh
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# -----------------------------------------------------------------------------
+# Apache Maven Build Log Viewer Script
+#
+# Environment Variable Prerequisites
+#
+#   JAVA_HOME           (Optional) Points to a Java installation.
+#   MAVEN_OPTS          (Optional) Java runtime options used when Maven is executed.
+#   MAVEN_SKIP_RC       (Optional) Flag to disable loading of mavenrc files.
+# -----------------------------------------------------------------------------
+
+"`dirname "$0"`/mvn" --log "$@"

apache-maven/src/assembly/maven/bin/mvnlog.cmd

@@ -0,0 +1,39 @@
+@REM Licensed to the Apache Software Foundation (ASF) under one
+@REM or more contributor license agreements.  See the NOTICE file
+@REM distributed with this work for additional information
+@REM regarding copyright ownership.  The ASF licenses this file
+@REM to you under the Apache License, Version 2.0 (the
+@REM "License"); you may not use this file except in compliance
+@REM with the License.  You may obtain a copy of the License at
+@REM
+@REM    http://www.apache.org/licenses/LICENSE-2.0
+@REM
+@REM Unless required by applicable law or agreed to in writing,
+@REM software distributed under the License is distributed on an
+@REM "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+@REM KIND, either express or implied.  See the License for the
+@REM specific language governing permissions and limitations
+@REM under the License.
+
+@REM -----------------------------------------------------------------------------
+@REM Apache Maven Build Log Viewer Script
+@REM
+@REM Environment Variable Prerequisites
+@REM
+@REM   JAVA_HOME           (Optional) Points to a Java installation.
+@REM   MAVEN_BATCH_ECHO    (Optional) Set to 'on' to enable the echoing of the batch commands.
+@REM   MAVEN_BATCH_PAUSE   (Optional) set to 'on' to wait for a key stroke before ending.
+@REM   MAVEN_OPTS          (Optional) Java runtime options used when Maven is executed.
+@REM   MAVEN_SKIP_RC       (Optional) Flag to disable loading of mavenrc files.
+@REM -----------------------------------------------------------------------------
+
+@REM Begin all REM lines with '@' in case MAVEN_BATCH_ECHO is 'on'
+@echo off
+@REM set title of command window
+title %0
+@REM enable echoing by setting MAVEN_BATCH_ECHO to 'on'
+@if "%MAVEN_BATCH_ECHO%"=="on" echo %MAVEN_BATCH_ECHO%
+
+@setlocal
+
+@call "%~dp0"mvn.cmd --log %*

api/maven-api-cli/src/main/java/org/apache/maven/api/cli/Options.java

@@ -182,6 +182,43 @@ public interface Options {
     @Nonnull
     Optional<String> color();
 
+    /**
+     * Returns the console output mode.
+     * <p>
+     * Supported modes:
+     * <ul>
+     *   <li>{@code "auto"} — selects {@code "plain"} in CI, {@code "rich"} on interactive TTYs,
+     *       {@code "verbose"} otherwise</li>
+     *   <li>{@code "plain"} — compact one-line-per-module output with structured summary</li>
+     *   <li>{@code "rich"} — JLine status bar with live reactor progress (requires TTY)</li>
+     *   <li>{@code "verbose"} — full mojo-level output (Maven 4.0 default behavior)</li>
+     *   <li>{@code "machine"} — JSON lines: one typed JSON object per lifecycle event,
+     *       designed for piping to external tools, CI systems, and LLM agents</li>
+     * </ul>
+     *
+     * @return an {@link Optional} containing the console mode, or empty if not set
+     * @since 4.1.0
+     */
+    @Nonnull
+    Optional<String> console();
+
+    /**
+     * Returns the warning display mode.
+     * <p>
+     * Controls how build warnings (diagnostics) are displayed:
+     * <ul>
+     *   <li>{@code "summary"} (default) — collect warnings, show deduplicated summary at end of build</li>
+     *   <li>{@code "all"} — show warnings inline as they occur AND show summary at end</li>
+     *   <li>{@code "none"} — suppress the diagnostic summary entirely</li>
+     *   <li>{@code "fail"} — show summary AND fail the build if any warnings exist</li>
+     * </ul>
+     *
+     * @return an {@link Optional} containing the warning mode, or empty if not set
+     * @since 4.1.0
+     */
+    @Nonnull
+    Optional<String> warningMode();
+
     /**
      * Indicates whether Maven should operate in offline mode.
      *

api/maven-api-cli/src/main/java/org/apache/maven/api/cli/ParserRequest.java

@@ -253,6 +253,30 @@ static Builder mvnup(@Nonnull List<String> args, @Nonnull MessageBuilderFactory
         return builder(Tools.MVNUP_CMD, Tools.MVNUP_NAME, args, messageBuilderFactory);
     }
 
+    /**
+     * Creates a new Builder instance for constructing a Maven Build Log Viewer ParserRequest.
+     *
+     * @param args the command-line arguments
+     * @param messageBuilderFactory the factory for creating message builders
+     * @return a new Builder instance
+     */
+    @Nonnull
+    static Builder mvnlog(@Nonnull String[] args, @Nonnull MessageBuilderFactory messageBuilderFactory) {
+        return mvnlog(Arrays.asList(args), messageBuilderFactory);
+    }
+
+    /**
+     * Creates a new Builder instance for constructing a Maven Build Log Viewer ParserRequest.
+     *
+     * @param args the command-line arguments
+     * @param messageBuilderFactory the factory for creating message builders
+     * @return a new Builder instance
+     */
+    @Nonnull
+    static Builder mvnlog(@Nonnull List<String> args, @Nonnull MessageBuilderFactory messageBuilderFactory) {
+        return builder(Tools.MVNLOG_CMD, Tools.MVNLOG_NAME, args, messageBuilderFactory);
+    }
+
     /**
      * Creates a new Builder instance for constructing a ParserRequest.
      *

api/maven-api-cli/src/main/java/org/apache/maven/api/cli/Tools.java

@@ -42,4 +42,7 @@ private Tools() {}
 
     public static final String MVNUP_CMD = "mvnup";
     public static final String MVNUP_NAME = "Maven Upgrade Tool";
+
+    public static final String MVNLOG_CMD = "mvnlog";
+    public static final String MVNLOG_NAME = "Maven Build Log Viewer";
 }

api/maven-api-cli/src/main/java/org/apache/maven/api/cli/mvnlog/LogOptions.java

@@ -0,0 +1,77 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api.cli.mvnlog;
+
+import java.util.Optional;
+
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.cli.Options;
+
+/**
+ * Defines the options specific to the Maven build log viewer tool ({@code mvnlog}).
+ * This interface extends the general {@link Options} interface, adding log-viewing options.
+ *
+ * @since 4.1.0
+ */
+@Experimental
+public interface LogOptions extends Options {
+    /**
+     * Whether to show detailed diagnostics (warnings and errors) from the build.
+     *
+     * @return an {@link Optional} containing {@code true} if diagnostics should be shown
+     */
+    Optional<Boolean> diagnostics();
+
+    /**
+     * Whether to show detailed failure information including stack traces.
+     *
+     * @return an {@link Optional} containing {@code true} if failures should be shown in detail
+     */
+    Optional<Boolean> failures();
+
+    /**
+     * Whether to show a full per-mojo timing breakdown.
+     *
+     * @return an {@link Optional} containing {@code true} if the full breakdown should be shown
+     */
+    Optional<Boolean> full();
+
+    /**
+     * Whether to list all available build reports instead of showing one.
+     *
+     * @return an {@link Optional} containing {@code true} if reports should be listed
+     */
+    Optional<Boolean> list();
+
+    /**
+     * Whether to output the raw JSON build report instead of formatted text.
+     * Useful for piping to tools like {@code jq} or for programmatic consumption.
+     *
+     * @return an {@link Optional} containing {@code true} if raw JSON should be output
+     */
+    Optional<Boolean> json();
+
+    /**
+     * Returns the path to a specific build report file to display.
+     * If not specified, defaults to {@code target/build-reports/build-report-latest.json}.
+     *
+     * @return an {@link Optional} containing the report file path, or empty if not specified
+     */
+    Optional<String> reportFile();
+}