Add integration tests and fix default reconciliation merging

- Created integration tests for three scenarios:
  * No executionControl configuration (defaults apply automatically)
  * executionControl with other plugin (defaults still apply to unconfigured plugins)
  * Explicit plugin config (overrides defaults for that plugin only)

- Implemented parameter export/categorization system:
  * Created plugin-parameters.xsd schema
  * Added maven-compiler-plugin.xml (57 parameters)
  * Added maven-install-plugin.xml (22 parameters)
  * Parameter validation with ERROR/WARN logging
  * Version-specific parameter support with best-match selection

- Implemented XML-based default reconciliation:
  * Created default-reconciliation.xsd schema
  * Created defaults.xml with maven-compiler-plugin and maven-install-plugin
  * Implemented DefaultReconciliationLoader to replace hardcoded defaults

- Updated documentation:
  * Clarified that defaults are built-in (not user-customizable)
  * Added example showing how to override defaults via .mvn/maven-build-cache-config.xml
  * Documented parameter validation and version-specific definitions

Author: cowwoc

src/main/java/org/apache/maven/buildcache/xml/CacheConfigImpl.java

@@ -118,6 +118,8 @@ public class CacheConfigImpl implements org.apache.maven.buildcache.xml.CacheCon
     private final XmlService xmlService;
     private final Provider<MavenSession> providerSession;
     private final RuntimeInformation rtInfo;
+    private final PluginParameterLoader parameterLoader;
+    private final DefaultReconciliationLoader defaultReconciliationLoader;
 
     private volatile CacheState state;
     private CacheConfig cacheConfig;
@@ -129,6 +131,8 @@ public CacheConfigImpl(XmlService xmlService, Provider<MavenSession> providerSes
         this.xmlService = xmlService;
         this.providerSession = providerSession;
         this.rtInfo = rtInfo;
+        this.parameterLoader = new PluginParameterLoader();
+        this.defaultReconciliationLoader = new DefaultReconciliationLoader();
     }
 
     @Nonnull
@@ -248,74 +252,190 @@ public boolean isLogAllProperties(MojoExecution mojoExecution) {
     }
 
     private GoalReconciliation findReconciliationConfig(MojoExecution mojoExecution) {
-        List<GoalReconciliation> reconciliation;
+        if (mojoExecution == null) {
+            return null;
+        }
 
-        if (cacheConfig.getExecutionControl() == null || cacheConfig.getExecutionControl().getReconcile() == null) {
-            // Use default reconciliation configs for common plugins
-            reconciliation = getDefaultReconciliationConfigs();
-        } else {
-            reconciliation = cacheConfig.getExecutionControl().getReconcile().getPlugins();
+        final String goal = mojoExecution.getGoal();
+        final Plugin plugin = mojoExecution.getPlugin();
+
+        if (plugin == null) {
+            return null;
         }
 
-        for (GoalReconciliation goalReconciliationConfig : reconciliation) {
-            final String goal = mojoExecution.getGoal();
+        // First check explicit configuration
+        if (cacheConfig.getExecutionControl() != null && cacheConfig.getExecutionControl().getReconcile() != null) {
+            List<GoalReconciliation> explicitConfigs =
+                    cacheConfig.getExecutionControl().getReconcile().getPlugins();
+            for (GoalReconciliation config : explicitConfigs) {
+                if (isPluginMatch(plugin, config) && Strings.CS.equals(goal, config.getGoal())) {
+                    // Validate explicit config against parameter definitions (with version)
+                    validateReconciliationConfig(config, plugin);
+                    return config;
+                }
+            }
+        }
 
-            if (isPluginMatch(mojoExecution.getPlugin(), goalReconciliationConfig)
-                    && Strings.CS.equals(goal, goalReconciliationConfig.getGoal())) {
-                return goalReconciliationConfig;
+        // Fall back to defaults if no explicit configuration found
+        List<GoalReconciliation> defaults = getDefaultReconciliationConfigs();
+        for (GoalReconciliation config : defaults) {
+            if (isPluginMatch(plugin, config) && Strings.CS.equals(goal, config.getGoal())) {
+                // Validate default config against parameter definitions (with version)
+                validateReconciliationConfig(config, plugin);
+                return config;
             }
         }
+
         return null;
     }
 
-    private List<GoalReconciliation> getDefaultReconciliationConfigs() {
-        List<GoalReconciliation> defaults = new ArrayList<>();
-
-        // maven-compiler-plugin:compile - track source, target, release
-        GoalReconciliation compilerCompile = new GoalReconciliation();
-        compilerCompile.setArtifactId("maven-compiler-plugin");
-        compilerCompile.setGoal("compile");
-
-        TrackedProperty source = new TrackedProperty();
-        source.setPropertyName("source");
-        compilerCompile.addReconcile(source);
-
-        TrackedProperty target = new TrackedProperty();
-        target.setPropertyName("target");
-        compilerCompile.addReconcile(target);
+    /**
+     * Validates a single reconciliation config against plugin parameter definitions.
+     * Uses plugin version to load the appropriate parameter definition.
+     */
+    private void validateReconciliationConfig(GoalReconciliation config, Plugin plugin) {
+        String artifactId = config.getArtifactId();
+        String goal = config.getGoal();
+        String pluginVersion = plugin.getVersion();
+
+        // Load parameter definition for this plugin with version
+        PluginParameterDefinition pluginDef = parameterLoader.load(artifactId, pluginVersion);
+
+        if (pluginDef == null) {
+            LOGGER.warn(
+                    "No parameter definition found for plugin {}:{} version {}. "
+                            + "Cannot validate reconciliation configuration. "
+                            + "Consider adding a parameter definition file to plugin-parameters/{}.xml",
+                    artifactId,
+                    goal,
+                    pluginVersion != null ? pluginVersion : "unknown",
+                    artifactId);
+            return;
+        }
 
-        TrackedProperty release = new TrackedProperty();
-        release.setPropertyName("release");
-        compilerCompile.addReconcile(release);
+        // Get goal definition
+        PluginParameterDefinition.GoalParameterDefinition goalDef = pluginDef.getGoal(goal);
+        if (goalDef == null) {
+            LOGGER.warn(
+                    "Goal '{}' not found in parameter definition for plugin {} version {}. "
+                            + "Cannot validate reconciliation configuration.",
+                    goal,
+                    artifactId,
+                    pluginVersion != null ? pluginVersion : "unknown");
+            return;
+        }
 
-        defaults.add(compilerCompile);
+        // Validate each tracked property
+        List<TrackedProperty> properties = config.getReconciles();
+        if (properties == null) {
+            return;
+        }
 
-        // maven-compiler-plugin:testCompile - track source, target, release
-        GoalReconciliation compilerTestCompile = new GoalReconciliation();
-        compilerTestCompile.setArtifactId("maven-compiler-plugin");
-        compilerTestCompile.setGoal("testCompile");
+        for (TrackedProperty property : properties) {
+            String propertyName = property.getPropertyName();
+
+            if (!goalDef.hasParameter(propertyName)) {
+                LOGGER.error(
+                        "Unknown parameter '{}' in reconciliation config for {}:{} version {}. "
+                                + "This may indicate a plugin version mismatch or renamed parameter. "
+                                + "Consider updating parameter definition or removing from reconciliation.",
+                        propertyName,
+                        artifactId,
+                        goal,
+                        pluginVersion != null ? pluginVersion : "unknown");
+            } else {
+                PluginParameterDefinition.ParameterDefinition paramDef = goalDef.getParameter(propertyName);
+                if (paramDef.isBehavioral()) {
+                    LOGGER.warn(
+                            "Parameter '{}' in reconciliation config for {}:{} is categorized as BEHAVIORAL. "
+                                    + "Behavioral parameters affect how the build runs but not the output. "
+                                    + "Consider removing if it doesn't actually affect build artifacts.",
+                            propertyName,
+                            artifactId,
+                            goal);
+                }
+            }
+        }
+    }
 
-        TrackedProperty testSource = new TrackedProperty();
-        testSource.setPropertyName("source");
-        compilerTestCompile.addReconcile(testSource);
+    /**
+     * Load default reconciliation configurations from XML.
+     * Defaults are loaded from classpath: default-reconciliation/defaults.xml
+     */
+    private List<GoalReconciliation> getDefaultReconciliationConfigs() {
+        List<GoalReconciliation> defaults = defaultReconciliationLoader.loadDefaults();
 
-        TrackedProperty testTarget = new TrackedProperty();
-        testTarget.setPropertyName("target");
-        compilerTestCompile.addReconcile(testTarget);
+        // Validate all default configurations against parameter definitions
+        validateReconciliationConfigs(defaults);
 
-        TrackedProperty testRelease = new TrackedProperty();
-        testRelease.setPropertyName("release");
-        compilerTestCompile.addReconcile(testRelease);
+        return defaults;
+    }
 
-        defaults.add(compilerTestCompile);
+    /**
+     * Validates reconciliation configs against plugin parameter definitions.
+     * Warns about unknown parameters that may indicate plugin changes or configuration errors.
+     */
+    private void validateReconciliationConfigs(List<GoalReconciliation> configs) {
+        for (GoalReconciliation config : configs) {
+            String artifactId = config.getArtifactId();
+            String goal = config.getGoal();
+
+            // Load parameter definition for this plugin
+            PluginParameterDefinition pluginDef = parameterLoader.load(artifactId);
+
+            if (pluginDef == null) {
+                LOGGER.warn(
+                        "No parameter definition found for plugin {}:{}. "
+                                + "Cannot validate reconciliation configuration. "
+                                + "Consider adding a parameter definition file to plugin-parameters/{}.xml",
+                        artifactId,
+                        goal,
+                        artifactId);
+                continue;
+            }
 
-        // maven-install-plugin:install - always run (empty reconciliation means it's tracked)
-        GoalReconciliation install = new GoalReconciliation();
-        install.setArtifactId("maven-install-plugin");
-        install.setGoal("install");
-        defaults.add(install);
+            // Get goal definition
+            PluginParameterDefinition.GoalParameterDefinition goalDef = pluginDef.getGoal(goal);
+            if (goalDef == null) {
+                LOGGER.warn(
+                        "Goal '{}' not found in parameter definition for plugin {}. "
+                                + "Cannot validate reconciliation configuration.",
+                        goal,
+                        artifactId);
+                continue;
+            }
 
-        return defaults;
+            // Validate each tracked property
+            List<TrackedProperty> properties = config.getReconciles();
+            if (properties != null) {
+                for (TrackedProperty property : properties) {
+                    String propertyName = property.getPropertyName();
+
+                    if (!goalDef.hasParameter(propertyName)) {
+                        LOGGER.error(
+                                "Unknown parameter '{}' in default reconciliation config for {}:{}. "
+                                        + "This parameter is not defined in the plugin parameter definition. "
+                                        + "This may indicate a plugin version mismatch or renamed parameter. "
+                                        + "Please update the parameter definition or remove this property from reconciliation.",
+                                propertyName,
+                                artifactId,
+                                goal);
+                    } else {
+                        PluginParameterDefinition.ParameterDefinition paramDef =
+                                goalDef.getParameter(propertyName);
+                        if (paramDef.isBehavioral()) {
+                            LOGGER.warn(
+                                    "Parameter '{}' in reconciliation config for {}:{} is categorized as BEHAVIORAL. "
+                                            + "Behavioral parameters typically should not affect cache invalidation. "
+                                            + "Consider removing this parameter from reconciliation if it doesn't affect build output.",
+                                    propertyName,
+                                    artifactId,
+                                    goal);
+                        }
+                    }
+                }
+            }
+        }
     }
 
     @Nonnull

src/main/java/org/apache/maven/buildcache/xml/DefaultReconciliationLoader.java

@@ -0,0 +1,126 @@
+/*
+ * 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.buildcache.xml;
+
+import javax.xml.parsers.DocumentBuilder;
+import javax.xml.parsers.DocumentBuilderFactory;
+
+import java.io.InputStream;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.apache.maven.buildcache.xml.config.GoalReconciliation;
+import org.apache.maven.buildcache.xml.config.TrackedProperty;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.w3c.dom.Document;
+import org.w3c.dom.Element;
+import org.w3c.dom.NodeList;
+
+/**
+ * Loads default reconciliation configurations from classpath resources.
+ * Default configs are stored in src/main/resources/default-reconciliation/defaults.xml
+ */
+public class DefaultReconciliationLoader {
+
+    private static final Logger LOGGER = LoggerFactory.getLogger(DefaultReconciliationLoader.class);
+    private static final String DEFAULTS_PATH = "default-reconciliation/defaults.xml";
+
+    private List<GoalReconciliation> cachedDefaults;
+
+    /**
+     * Load default reconciliation configurations from XML
+     */
+    public List<GoalReconciliation> loadDefaults() {
+        if (cachedDefaults != null) {
+            return cachedDefaults;
+        }
+
+        InputStream is = getClass().getClassLoader().getResourceAsStream(DEFAULTS_PATH);
+
+        if (is == null) {
+            LOGGER.warn("No default reconciliation configuration found at {}", DEFAULTS_PATH);
+            cachedDefaults = new ArrayList<>();
+            return cachedDefaults;
+        }
+
+        try {
+            cachedDefaults = parseDefaults(is);
+            LOGGER.info("Loaded {} default reconciliation configurations", cachedDefaults.size());
+            return cachedDefaults;
+        } catch (Exception e) {
+            LOGGER.warn("Failed to load default reconciliation configurations: {}", e.getMessage(), e);
+            cachedDefaults = new ArrayList<>();
+            return cachedDefaults;
+        }
+    }
+
+    private List<GoalReconciliation> parseDefaults(InputStream is) throws Exception {
+        List<GoalReconciliation> defaults = new ArrayList<>();
+
+        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
+        factory.setNamespaceAware(true);
+        DocumentBuilder builder = factory.newDocumentBuilder();
+        Document doc = builder.parse(is);
+
+        Element root = doc.getDocumentElement();
+        NodeList pluginNodes = root.getElementsByTagName("plugin");
+
+        for (int i = 0; i < pluginNodes.getLength(); i++) {
+            Element pluginElement = (Element) pluginNodes.item(i);
+            GoalReconciliation config = parsePlugin(pluginElement);
+            defaults.add(config);
+        }
+
+        return defaults;
+    }
+
+    private GoalReconciliation parsePlugin(Element pluginElement) {
+        String artifactId = getTextContent(pluginElement, "artifactId");
+        String goal = getTextContent(pluginElement, "goal");
+
+        GoalReconciliation config = new GoalReconciliation();
+        config.setArtifactId(artifactId);
+        config.setGoal(goal);
+
+        // Parse properties if present
+        NodeList propertiesNodes = pluginElement.getElementsByTagName("properties");
+        if (propertiesNodes.getLength() > 0) {
+            Element propertiesElement = (Element) propertiesNodes.item(0);
+            NodeList propertyNodes = propertiesElement.getElementsByTagName("property");
+
+            for (int i = 0; i < propertyNodes.getLength(); i++) {
+                String propertyName = propertyNodes.item(i).getTextContent().trim();
+                TrackedProperty property = new TrackedProperty();
+                property.setPropertyName(propertyName);
+                config.addReconcile(property);
+            }
+        }
+
+        return config;
+    }
+
+    private String getTextContent(Element parent, String tagName) {
+        NodeList nodes = parent.getElementsByTagName(tagName);
+        if (nodes.getLength() > 0) {
+            return nodes.item(0).getTextContent().trim();
+        }
+        return null;
+    }
+}