gnodet-bot commented on code in PR #14066:
URL: https://github.com/apache/maven/pull/14066#discussion_r4642300904


##########
api/maven-api-log/src/main/java/org/apache/maven/api/logging/LogEventBuilder.java:
##########
@@ -0,0 +1,194 @@
+/*
+ * 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.logging;
+
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+
+/**
+ * Fluent builder for a single log statement.
+ * <p>
+ * Instances are obtained from {@link Logger#atTrace()}, {@link 
Logger#atDebug()}, etc.
+ * A builder <em>must</em> be consumed in a single chained call; it must not be
+ * stored in a variable across statements, as implementations may reuse
+ * thread-local state for zero-allocation dispatch.
+ * <p>
+ * When the target level is disabled the {@code Logger} returns a shared
+ * {@code NopLogEventBuilder} singleton, making the entire fluent call chain a 
no-op
+ * with zero allocations.
+ *
+ * <pre>{@code
+ * log.atInfo()
+ *    .withKeyValue("module", module.getId())
+ *    .log("Compiling {} source files", count);
+ * }</pre>
+ *
+ * <h2>Message format</h2>
+ * <p>
+ * The {@code log(String format, Object...)} family of methods uses a simple
+ * positional placeholder syntax: each occurrence of {@code {}} in the format
+ * string is replaced, in order, by the string representation of the 
corresponding
+ * argument. No index, type specifier, or locale conversion is supported — 
this is
+ * intentionally simpler than {@link java.text.MessageFormat} and avoids the
+ * injection risk of {@code printf}-style specifiers.
+ * <p>
+ * Example: {@code log("Building {} module(s) in {}", count, dir)} produces
+ * {@code "Building 3 module(s) in /tmp/build"} when {@code count=3} and
+ * {@code dir="/tmp/build"}.
+ * <p>
+ * This convention is the same as the one used by SLF4J
+ * (<a 
href="https://www.slf4j.org/api/org/slf4j/helpers/MessageFormatter.html";>MessageFormatter</a>),
+ * which is widely used in the Java ecosystem and is already the format 
employed
+ * by {@code plugin.Log}, the API this interface replaces.
+ *
+ * @since 4.0.0
+ */
+@Experimental
+public interface LogEventBuilder {
+
+    /**
+     * Attaches a structured key-value pair to this log event.
+     * <p>
+     * Structured key-value pairs are consumed by structured log appenders
+     * (e.g. JSON, ECS, or Logstash layouts in Logback or Log4j 2) that capture
+     * fields alongside the message text — rather than embedding metadata 
inside the
+     * message string itself. This enables log aggregators such as 
Elasticsearch or
+     * Splunk to filter and correlate events by field values directly.
+     * <p>
+     * In a Maven context, typical uses include attaching build metadata such 
as
+     * project coordinates, mojo identifiers, and elapsed time as first-class 
indexed
+     * fields. When running with a plain-text appender these pairs are 
silently ignored
+     * or appended after the message, depending on the appender configuration.
+     *
+     * @param key   the field name, never {@code null}
+     * @param value the string value
+     * @return this builder
+     */
+    @Nonnull
+    LogEventBuilder withKeyValue(@Nonnull String key, String value);
+
+    /**
+     * Attaches a structured key-value pair with a {@code long} value.
+     * <p>
+     * See {@link #withKeyValue(String, String)} for the purpose of structured 
key-value pairs.
+     *
+     * @param key   the field name, never {@code null}
+     * @param value the numeric value
+     * @return this builder
+     */
+    @Nonnull
+    LogEventBuilder withKeyValue(@Nonnull String key, long value);
+
+    /**
+     * Attaches a structured key-value pair with a {@code boolean} value.
+     * <p>
+     * See {@link #withKeyValue(String, String)} for the purpose of structured 
key-value pairs.
+     *
+     * @param key   the field name, never {@code null}
+     * @param value the boolean value
+     * @return this builder
+     */
+    @Nonnull
+    LogEventBuilder withKeyValue(@Nonnull String key, boolean value);
+
+    /**
+     * Attaches a {@link Throwable} to this log event.
+     *
+     * @param t the throwable, may be {@code null} (no-op)
+     * @return this builder
+     */
+    @Nonnull
+    LogEventBuilder withThrowable(Throwable t);

Review Comment:
   ⚠️ **Missing `@Nullable` on parameter** — the Javadoc says `@param t the 
throwable, may be {@code null} (no-op)` but the parameter has no `@Nullable` 
annotation. `LogEventBuilder.java` only imports `@Nonnull`; `@Nullable` must be 
added to the import block too. Without it, IntelliJ/SpotBugs null-analysis 
produces a false-positive warning when callers pass `null` to clear the 
throwable.
   
   ```suggestion
       LogEventBuilder withThrowable(@Nullable Throwable t);
   ```
   
   And add to the imports:
   ```
   import org.apache.maven.api.annotations.Nullable;
   ```



##########
api/maven-api-log/src/main/java/org/apache/maven/api/logging/Logger.java:
##########
@@ -0,0 +1,350 @@
+/*
+ * 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.logging;
+
+import java.util.function.Supplier;
+
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.annotations.Nullable;
+import org.apache.maven.api.annotations.Provider;
+
+/**
+ * Unified logging interface for Maven plugins and CLI bootstrap code.
+ * <p>
+ * Unified interface that supports a fluent builder API, structured key-value
+ * pairs, and lazy message evaluation. Used by both mojo logging and CLI
+ * bootstrap logging.
+ * <p>
+ * Instances are obtained via dependency injection. A {@code @Singleton} bean
+ * may hold a long-lived {@code Logger} instance safely: context fields such as
+ * {@code projectId} and {@code mojoId} are resolved from a per-thread
+ * {@code LogContext} at event dispatch time, not at injection time.

Review Comment:
   ⚠️ **`LogContext` does not exist** — "context fields such as `projectId` and 
`mojoId` are resolved from a per-thread `LogContext` at event dispatch time, 
not at injection time." `LogContext` is not defined anywhere in this 
repository. Remove this claim; callers who read it will expect 
ThreadLocal-based context enrichment that the implementation does not provide.



##########
api/maven-api-log/src/main/java/org/apache/maven/api/logging/LogEventBuilder.java:
##########
@@ -0,0 +1,194 @@
+/*
+ * 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.logging;
+
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+
+/**
+ * Fluent builder for a single log statement.
+ * <p>
+ * Instances are obtained from {@link Logger#atTrace()}, {@link 
Logger#atDebug()}, etc.
+ * A builder <em>must</em> be consumed in a single chained call; it must not be
+ * stored in a variable across statements, as implementations may reuse
+ * thread-local state for zero-allocation dispatch.
+ * <p>
+ * When the target level is disabled the {@code Logger} returns a shared
+ * {@code NopLogEventBuilder} singleton, making the entire fluent call chain a 
no-op
+ * with zero allocations.
+ *
+ * <pre>{@code
+ * log.atInfo()
+ *    .withKeyValue("module", module.getId())
+ *    .log("Compiling {} source files", count);
+ * }</pre>
+ *
+ * <h2>Message format</h2>
+ * <p>
+ * The {@code log(String format, Object...)} family of methods uses a simple
+ * positional placeholder syntax: each occurrence of {@code {}} in the format
+ * string is replaced, in order, by the string representation of the 
corresponding
+ * argument. No index, type specifier, or locale conversion is supported — 
this is
+ * intentionally simpler than {@link java.text.MessageFormat} and avoids the
+ * injection risk of {@code printf}-style specifiers.
+ * <p>
+ * Example: {@code log("Building {} module(s) in {}", count, dir)} produces
+ * {@code "Building 3 module(s) in /tmp/build"} when {@code count=3} and
+ * {@code dir="/tmp/build"}.
+ * <p>
+ * This convention is the same as the one used by SLF4J
+ * (<a 
href="https://www.slf4j.org/api/org/slf4j/helpers/MessageFormatter.html";>MessageFormatter</a>),
+ * which is widely used in the Java ecosystem and is already the format 
employed
+ * by {@code plugin.Log}, the API this interface replaces.
+ *
+ * @since 4.0.0
+ */
+@Experimental
+public interface LogEventBuilder {
+
+    /**
+     * Attaches a structured key-value pair to this log event.
+     * <p>
+     * Structured key-value pairs are consumed by structured log appenders
+     * (e.g. JSON, ECS, or Logstash layouts in Logback or Log4j 2) that capture
+     * fields alongside the message text — rather than embedding metadata 
inside the
+     * message string itself. This enables log aggregators such as 
Elasticsearch or
+     * Splunk to filter and correlate events by field values directly.
+     * <p>
+     * In a Maven context, typical uses include attaching build metadata such 
as
+     * project coordinates, mojo identifiers, and elapsed time as first-class 
indexed
+     * fields. When running with a plain-text appender these pairs are 
silently ignored
+     * or appended after the message, depending on the appender configuration.
+     *
+     * @param key   the field name, never {@code null}
+     * @param value the string value
+     * @return this builder
+     */
+    @Nonnull
+    LogEventBuilder withKeyValue(@Nonnull String key, String value);
+
+    /**
+     * Attaches a structured key-value pair with a {@code long} value.
+     * <p>
+     * See {@link #withKeyValue(String, String)} for the purpose of structured 
key-value pairs.
+     *
+     * @param key   the field name, never {@code null}
+     * @param value the numeric value
+     * @return this builder
+     */
+    @Nonnull
+    LogEventBuilder withKeyValue(@Nonnull String key, long value);
+
+    /**
+     * Attaches a structured key-value pair with a {@code boolean} value.
+     * <p>
+     * See {@link #withKeyValue(String, String)} for the purpose of structured 
key-value pairs.
+     *
+     * @param key   the field name, never {@code null}
+     * @param value the boolean value
+     * @return this builder
+     */
+    @Nonnull
+    LogEventBuilder withKeyValue(@Nonnull String key, boolean value);
+
+    /**
+     * Attaches a {@link Throwable} to this log event.
+     *
+     * @param t the throwable, may be {@code null} (no-op)
+     * @return this builder
+     */
+    @Nonnull
+    LogEventBuilder withThrowable(Throwable t);
+
+    /**
+     * Overrides the project identifier for this event.
+     * <p>
+     * The default path resolves {@code projectId} from the current thread's
+     * {@code LogContext}; use this method only in the rare cases where the
+     * ThreadLocal context is incorrect (e.g. async hand-offs).

Review Comment:
   ⚠️ **`LogContext` does not exist** — this description says "The default path 
resolves `projectId` from the current thread's `LogContext`; use this method 
only in the rare cases where the ThreadLocal context is incorrect (e.g. async 
hand-offs)." But `LogContext` is not defined anywhere in this repository, and 
`DefaultLogEventBuilder.withProjectId` is a silent no-op (`return this`). This 
description inverts the truth: it implies enrichment happens automatically and 
this method is for overriding it, when in fact enrichment never happens at all. 
The description should match the actual implementation — that enrichment is 
best-effort and the built-in implementation silently ignores the value.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to