gnodet opened a new issue, #13987:
URL: https://github.com/apache/maven/issues/13987
## Motivation
During a discussion about incremental builds for plugins that don't
implement the `IncrementalBuildContext` API (e.g. `frontend-maven-plugin`
running `npm ci`), it became clear that there is no v4 API/SPI entry point
allowing an extension to **dynamically decide — at execution time — whether to
skip a mojo** based on runtime state (file hashes, timestamps, external
signals).
The existing options are insufficient:
- `MojoExecutionFilter` / `maven.lifecycle.filter` — static, resolved once
at plan time from a user property string; no access to the filesystem or build
state
- `ExecutionListener` — read-only; `RuntimeException` is caught and
swallowed; cannot veto execution
- `LifecyclePlan` transformer — operates on the plan snapshot before
execution; misses the concurrent build path where `BuildPlanExecutor` runs
directly without going through `LifecycleExecutor.execute()`
- `ProjectTransformer` — model-level, too early; no execution context
## Proposed Design
### 1. `MojoExecution.withConfiguration(XmlNode)` (prerequisite)
`MojoExecution` is `@Immutable` since #13366. The transformer needs to be
able to return a modified copy (e.g. to inject `<skip>true</skip>` into the
configuration). Following the pattern already used by `Model`,
`PluginExecution`, etc.:
```java
// On the MojoExecution interface
MojoExecution withConfiguration(XmlNode configuration);
// or via a builder:
interface Builder {
Builder configuration(XmlNode configuration);
MojoExecution build();
}
static Builder newBuilder(MojoExecution source) { ... }
```
### 2. `MojoExecutionTransformer` SPI
```java
// org.apache.maven.api.spi.MojoExecutionTransformer
@Consumer
public interface MojoExecutionTransformer extends SpiService {
sealed interface Decision permits Proceed, Skip {}
/** Continue with this execution (possibly with a modified
configuration). */
record Proceed(MojoExecution execution) implements Decision {}
/** Skip this execution entirely, logging the given reason. */
record Skip(String reason) implements Decision {}
/**
* Called after mojo setup (descriptor resolution + configuration
merging) but before
* the mojo is instantiated and populated. The transformer may return:
* - {@code Proceed(execution)} — run the mojo, optionally with a
modified configuration
* - {@code Proceed(execution.withConfiguration(...))} — run with
overridden config
* - {@code Skip("reason")} — skip this mojo execution entirely
*/
Decision transform(Session session, Project project, MojoExecution
execution)
throws MavenException;
/**
* Called after the mojo execution completes successfully.
* Use this to persist fingerprints, hashes, or other state for the next
build.
*/
default void afterExecution(Session session, Project project,
MojoExecution execution)
throws MavenException {}
}
```
### 3. Runtime wiring
The transformer must be called in the execution hot path — **after**
`setupMojoExecution()` (so the configuration is fully merged and finalized) but
**before** `DefaultBuildPluginManager.executeMojo()` / `getConfiguredMojo()`
(so the skip is a true skip, not a thrown exception, and the plugin realm is
never loaded).
The natural insertion point is in `MojoExecutor.execute(session,
mojoExecution, dependencyContext)` and its concurrent equivalent in
`BuildPlanExecutor.configureAndExecuteStep()`, parallel to where
`MojoExecutionFilter` is applied today.
## Concrete use case
An extension that skips `npm ci` when `package-lock.json` hasn't changed:
```java
public class NpmCiIncrementalTransformer implements MojoExecutionTransformer
{
@Override
public Decision transform(Session session, Project project,
MojoExecution execution) {
if (!isNpmCi(execution)) return new Proceed(execution);
Path lockFile = project.getBasedir().resolve("package-lock.json");
String currentHash = sha256(lockFile);
String storedHash = readStoredHash(project);
if (currentHash.equals(storedHash)) {
return new Skip("package-lock.json unchanged (hash=" +
currentHash + ")");
}
return new Proceed(execution);
}
@Override
public void afterExecution(Session session, Project project,
MojoExecution execution) {
// persist the hash for the next build
writeStoredHash(project,
sha256(project.getBasedir().resolve("package-lock.json")));
}
}
```
## Related
- #13983 — incremental build context API (plugin-side; this issue covers the
extension/user side)
- #13517 — partial/filtered lifecycle execution for IDE embedders
(complementary)
- #13499 — v4 API/SPI gaps tracking
- `maven.lifecycle.filter` / `MojoExecutionFilter` — existing static filter,
insufficient for dynamic use
- cc76fd30 — `MojoExecution` made `@Immutable` (prerequisite: add
`withConfiguration`)
--
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]