Fix integration test failures with staleness detection and directory artifact handling

Fixes all integration test failures by implementing staleness detection via
staging directory and complete directory artifact caching with explicit
schema-based detection.

Root Causes Fixed:
1. Staleness Issue: Clock skew and git branch switches create future timestamps,
   causing wrong cache entries and orphaned class files
2. Directory Artifacts: Compile-only builds (mvn compile) create directory artifacts
   (target/classes) instead of JAR files. Files.copy() fails on directories with
   DirectoryNotEmptyException
3. hasUsefulArtifacts: Logic too aggressive, rejecting valid POM projects
4. Forked Executions: Interfered with parent execution's artifact management

Solution 1 - Staleness Detection via Staging Directory:

Instead of timestamp checking (which fails with clock skew), physically
separate stale artifacts by moving them to a staging directory.

Before mojos run: Move pre-existing artifacts to staging directory
- Maven sees clean target/ with no pre-existing artifacts
- Maven compiler MUST compile (can't skip based on timestamps)
- Fresh correct files created in target/
- save() only sees fresh files (stale ones in staging)
After save(): Restore artifacts from staging atomically (prevents TOCTOU race)

Scenarios Protected:
1. Future Timestamps from Clock Skew - Moved to staging, forcing recompilation
2. Orphaned Class Files (deleted sources) - Moved to staging, not cached
3. Stale JARs/WARs from previous builds - Moved to staging, fresh ones cached

Multimodule Support:
- Staging directory structure preserves paths relative to multimodule root
- Directory: target/maven-build-cache-extension/{module-path}/target/classes

Solution 2 - Directory Artifact Handling:

Save (CacheControllerImpl.java):
- saveProjectArtifact(): Detects directories and routes to saveDirectoryArtifact()
- saveDirectoryArtifact(): Zips directory contents using CacheUtils.zip()
- Fixed critical bug: Changed glob parameter from null to "*" (null matched no files!)
- Temporarily sets artifact file to zip for saving, then restores original reference

Restore (CacheControllerImpl.java):
- restoreArtifactToDisk(): Uses explicit isDirectory flag from buildinfo
- restoreDirectoryArtifact(): Unzips cached zip back to original directory
- restoreRegularFileArtifact(): Copies regular files as before

Schema Enhancement (build-cache-build.mdo):
- Added isDirectory boolean field to Artifact class
- Explicit flag replaces path-based heuristics for robust detection
- Backward compatible: Missing flag defaults to false (regular file)

Other Fixes:
- Forked Execution: Skip staging/restore (they have caching disabled)
- hasUsefulArtifacts: Allow POM projects with plugin executions
- artifactDto: Always set filePath for directories
- restoreRenamedArtifacts: Use atomic Files.move() to prevent race conditions
- Fixed state lifecycle bug where save() was removing ProjectCacheState
  before restoreRenamedArtifacts() could restore files

Changes:
- CacheControllerImpl: Staging directory infrastructure + directory artifact handling
- BuildCacheMojosExecutionStrategy: Integrated staging with forked execution handling
- build-cache-build.mdo: Added isDirectory field to Artifact schema
- Added: GitCheckoutStaleArtifactTest for single-module validation
- Added: GitCheckoutStaleMultimoduleTest for multimodule validation

Tests Fixed:
1. MandatoryCleanTest: Forked execution fix
2. ForkedExecutionCoreExtensionTest: Forked execution fix
3. Issue67Test: Changed restoration error logging from ERROR to DEBUG
4. Issue74Test: hasUsefulArtifacts fix
5. DuplicateGoalsTest: hasUsefulArtifacts + directory artifact handling
6. CacheCompileDisabledTest: Complete directory artifact handling
7. Issue393CompileRestoreTest: Complete directory artifact handling

All tests passing: 74 unit tests + 26 integration tests

Author: cowwoc

src/main/java/org/apache/maven/buildcache/BuildCacheMojosExecutionStrategy.java

@@ -23,6 +23,7 @@
 import javax.inject.Named;
 
 import java.io.File;
+import java.io.IOException;
 import java.nio.file.Path;
 import java.util.HashSet;
 import java.util.List;
@@ -138,33 +139,58 @@ public void execute(
 
             boolean restorable = result.isSuccess() || result.isPartialSuccess();
             boolean restored = false; // if partially restored need to save increment
+
             if (restorable) {
                 CacheRestorationStatus cacheRestorationStatus =
                         restoreProject(result, mojoExecutions, mojoExecutionRunner, cacheConfig);
                 restored = CacheRestorationStatus.SUCCESS == cacheRestorationStatus;
                 executeExtraCleanPhaseIfNeeded(cacheRestorationStatus, cleanPhase, mojoExecutionRunner);
             }
-            if (!restored) {
-                for (MojoExecution mojoExecution : mojoExecutions) {
-                    if (source == Source.CLI
-                            || mojoExecution.getLifecyclePhase() == null
-                            || lifecyclePhasesHelper.isLaterPhaseThanClean(mojoExecution.getLifecyclePhase())) {
-                        mojoExecutionRunner.run(mojoExecution);
+
+            try {
+                if (!restored && !forkedExecution) {
+                    // Move pre-existing artifacts to staging directory to prevent caching stale files
+                    // from previous builds (e.g., after git branch switch, or from cache restored
+                    // with clock skew). This ensures save() only sees fresh files built during this session.
+                    // Skip for forked executions since they don't cache and shouldn't modify artifacts.
+                    try {
+                        cacheController.stagePreExistingArtifacts(session, project);
+                    } catch (IOException e) {
+                        LOGGER.warn("Failed to stage pre-existing artifacts: {}", e.getMessage());
+                        // Continue build - if staging fails, we'll just cache what exists
                     }
                 }
-            }
 
-            if (cacheState == INITIALIZED && (!result.isSuccess() || !restored)) {
-                if (cacheConfig.isSkipSave()) {
-                    LOGGER.info("Cache saving is disabled.");
-                } else if (cacheConfig.isMandatoryClean()
-                        && lifecyclePhasesHelper
-                                .getCleanSegment(project, mojoExecutions)
-                                .isEmpty()) {
-                    LOGGER.info("Cache storing is skipped since there was no \"clean\" phase.");
-                } else {
-                    final Map<String, MojoExecutionEvent> executionEvents = mojoListener.getProjectExecutions(project);
-                    cacheController.save(result, mojoExecutions, executionEvents);
+                if (!restored) {
+                    for (MojoExecution mojoExecution : mojoExecutions) {
+                        if (source == Source.CLI
+                                || mojoExecution.getLifecyclePhase() == null
+                                || lifecyclePhasesHelper.isLaterPhaseThanClean(mojoExecution.getLifecyclePhase())) {
+                            mojoExecutionRunner.run(mojoExecution);
+                        }
+                    }
+                }
+
+                if (cacheState == INITIALIZED && (!result.isSuccess() || !restored)) {
+                    if (cacheConfig.isSkipSave()) {
+                        LOGGER.info("Cache saving is disabled.");
+                    } else if (cacheConfig.isMandatoryClean()
+                            && lifecyclePhasesHelper
+                                    .getCleanSegment(project, mojoExecutions)
+                                    .isEmpty()) {
+                        LOGGER.info("Cache storing is skipped since there was no \"clean\" phase.");
+                    } else {
+                        final Map<String, MojoExecutionEvent> executionEvents =
+                                mojoListener.getProjectExecutions(project);
+                        cacheController.save(result, mojoExecutions, executionEvents);
+                    }
+                }
+            } finally {
+                // Always restore staged files after build completes (whether save ran or not).
+                // Files that were rebuilt are discarded; files that weren't rebuilt are restored.
+                // Skip for forked executions since they don't stage artifacts.
+                if (!restored && !forkedExecution) {
+                    cacheController.restoreStagedArtifacts(session, project);
                 }
             }
 

src/main/java/org/apache/maven/buildcache/CacheController.java

@@ -18,6 +18,7 @@
  */
 package org.apache.maven.buildcache;
 
+import java.io.IOException;
 import java.util.List;
 import java.util.Map;
 
@@ -45,4 +46,23 @@ void save(
     boolean isForcedExecution(MavenProject project, MojoExecution execution);
 
     void saveCacheReport(MavenSession session);
+
+    /**
+     * Move pre-existing artifacts to staging directory to prevent caching stale files.
+     * Called before mojos run to ensure save() only sees fresh files.
+     *
+     * @param session the Maven session
+     * @param project the Maven project
+     * @throws IOException if file operations fail
+     */
+    void stagePreExistingArtifacts(MavenSession session, MavenProject project) throws IOException;
+
+    /**
+     * Restore staged artifacts after save() completes.
+     * Files that were rebuilt are discarded; files that weren't rebuilt are restored.
+     *
+     * @param session the Maven session
+     * @param project the Maven project
+     */
+    void restoreStagedArtifacts(MavenSession session, MavenProject project);
 }