Add incremental build context API and implementation

[gnodet]

Summary

Port and modernize the incremental build context from PR #1118 for Maven 4.1.0. This gives mojo authors a first-class API for incremental builds — tracking which input files changed, managing input→output associations, skipping unnecessary work, and cleaning up stale outputs automatically.

Closes #1118.

What's in this PR

Public API (maven-api-core) — 17 types in 2 packages

org.apache.maven.api.build.context — mojo-facing API:

Type	Role
BuildContext	Main entry point — register inputs/outputs, check status, associate files
Input / Output	Tracked input and output resources with status and metadata
InputSet	Aggregation support (many inputs → one output, e.g., JAR, index)
Metadata<R>	Lazy status inspection before committing to process
Resource	Base for Input/Output — path, status, diagnostic messages
Status	Change status enum: NEW, MODIFIED, UNMODIFIED, REMOVED
Severity	Diagnostic severity: ERROR, WARNING, INFO
@Incremental	Annotation for mojo fields — marks config parameters for change detection
BuildContextException	Runtime exception (extends MavenException)

org.apache.maven.api.build.context.spi — integration/IDE SPI:

Type	Role
Workspace	Filesystem abstraction with 4 modes (NORMAL, DELTA, ESCALATED, SUPPRESSED)
CommittableBuildContext	Extended BuildContext with commit(Sink) for state persistence
BuildContextEnvironment	Construction parameters (state file, workspace, config, finalizer)
BuildContextFinalizer	Batch-commits all contexts after mojo success
Sink	Receives diagnostic messages during commit (bridges to IDE markers / Maven log)
FileState / Message	Immutable value objects for file metadata and diagnostics

Implementation (maven-impl) — 12 classes + 10 test classes

Core incremental build engine in org.apache.maven.internal.build.context.impl:

• DefaultBuildContext — full lifecycle: register inputs → detect changes → manage outputs → persist state
• Change detection via timestamp/size comparison with configurable workspace modes
• FileMatcher — Ant-style glob patterns with trie-based subdirectory optimization for targeted workspace walks
• State serialization/deserialization with cross-build state persistence
• 41 tests covering: status transitions across build cycles, input-output association cleanup, state serialization (including corrupt/incompatible files), include/exclude patterns, cross-platform paths (via Jimfs), configuration change escalation, delta workspace mode, diagnostic message persistence, aggregation lifecycle

Maven integration (maven-core) — 5 classes

Maven-specific wiring in org.apache.maven.internal.build.context.impl.maven:

• MavenBuildContext — @MojoExecutionScoped build context with Supplier-based delegation
• MavenBuildContextFinalizer — WeakMojoExecutionListener that batch-commits after mojo success
• MavenBuildContextConfiguration — resolves state file location from MojoExecution
• ProjectWorkspace — dispatches in-project paths to IDE workspace, out-of-project to filesystem
• Digest utilities (ClasspathDigester, MojoConfigurationDigester, Digesters) — detect plugin classpath and mojo configuration changes

Key design decisions

1. API in o.a.m.api.build.context (not o.a.m.api.build) — avoids package collision with the build report API in PR Build Report Foundation — structured report, console modes, warning control #12572

2. Workspace abstraction — the same mojo code works in CLI Maven (NORMAL mode with full filesystem scan), IDEs (DELTA mode with file-watcher), recovery scenarios (ESCALATED), and read-only analysis (SUPPRESSED)

3. Two-phase registration — registerInputs() returns Metadata<Input> for status inspection; process() commits to work. registerAndProcessInputs() provides a one-step convenience

4. Maven 4 DI — uses org.apache.maven.api.di.Inject/Named/Typed/MojoExecutionScoped and java.util.function.Supplier instead of javax.inject.* / org.eclipse.sisu.*

5. No external dependencies — replaced plexus-utils MatchPatterns with regex-based antPatternToRegex(), replaced CachingOutputStream with BufferedOutputStream(Files.newOutputStream())

Maven 4 conventions followed

• @Experimental on all API types
• @Nonnull / @Nullable on all parameters and return types
• @Immutable on value objects (FileState, Message)
• @Consumer / @Provider on SPI interfaces
• @since 4.1.0 on all public types
• BuildContextException extends MavenException
• Boolean accessor: isFailOnError() (not getFailOnError())
• Package-private test classes and methods (no public)

Known limitations (documented in Javadoc)

• No cross-module/reactor-level incremental coordination (build context is per-mojo-execution)
• @Incremental annotation lives in build.context rather than plugin.annotations
• Severity enum is separate from BuilderProblem.Severity (different semantics — build context messages persist across builds and support INFO level)

Test plan

• 41 build context tests passing in maven-impl
• mvn verify passes for maven-impl and maven-core (checkstyle, RAT, all tests)
• CI build passes

🤖 Generated with Claude Code