AbstractUpgradeGoal.java

/*
 * 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.cling.invoker.mvnup.goals;

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Map;

import org.apache.maven.api.cli.mvnup.UpgradeOptions;
import org.apache.maven.api.di.Inject;
import org.apache.maven.cling.invoker.mvnup.Goal;
import org.apache.maven.cling.invoker.mvnup.UpgradeContext;
import org.jdom2.Document;
import org.jdom2.JDOMException;
import org.jdom2.output.Format;
import org.jdom2.output.XMLOutputter;

import static org.apache.maven.cling.invoker.mvnup.goals.UpgradeConstants.Files.MVN_DIRECTORY;
import static org.apache.maven.cling.invoker.mvnup.goals.UpgradeConstants.ModelVersions.MODEL_VERSION_4_1_0;

/**
 * Base class for upgrade goals containing shared functionality.
 * Subclasses only differ in whether they save modifications to disk.
 *
 * <h2>Supported Upgrades</h2>
 *
 * <h3>Model Version Upgrades</h3>
 * <ul>
 *   <li><strong>4.0.0 ��� 4.1.0</strong>: Upgrades Maven 3.x POMs to Maven 4.1.0 format</li>
 * </ul>
 *
 * <h3>4.0.0 ��� 4.1.0 Upgrade Process</h3>
 * <ol>
 *   <li><strong>Namespace Update</strong>: Changes namespace from Maven 4.0.0 to 4.1.0 for all elements</li>
 *   <li><strong>Schema Location Update</strong>: Updates xsi:schemaLocation to Maven 4.1.0 XSD</li>
 *   <li><strong>Module Conversion</strong>: Converts {@code <modules>} to {@code <subprojects>} and {@code <module>} to {@code <subproject>}</li>
 *   <li><strong>Model Version Update</strong>: Updates {@code <modelVersion>} to 4.1.0</li>
 * </ol>
 *
 * <h3>Default Behavior</h3>
 * If no specific options are provided, the tool applies {@code --fix-model} and {@code --plugins} by default to ensure Maven 4 compatibility.
 *
 * <h3>All-in-One Option</h3>
 * The {@code --all} option is a convenience flag equivalent to {@code --model 4.1.0 --infer --fix-model --plugins}.
 * It performs a complete upgrade to Maven 4.1.0 with all optimizations, compatibility fixes, and plugin upgrades.
 *
 * <h3>Maven 4 Compatibility Fixes</h3>
 * When {@code --fix-model} option is enabled (or by default), applies fixes for Maven 4 compatibility issues:
 * <ul>
 *   <li><strong>Unsupported combine.children Attributes</strong>: Changes 'override' to 'merge' (Maven 4 only supports 'append' and 'merge')</li>
 *   <li><strong>Unsupported combine.self Attributes</strong>: Changes 'append' to 'merge' (Maven 4 only supports 'override', 'merge', and 'remove')</li>
 *   <li><strong>Duplicate Dependencies</strong>: Removes duplicate dependency declarations that Maven 4 strictly validates</li>
 *   <li><strong>Duplicate Plugins</strong>: Removes duplicate plugin declarations that Maven 4 strictly validates</li>
 *   <li><strong>Unsupported Repository Expressions</strong>: Comments out repositories with expressions not supported by Maven 4</li>
 *   <li><strong>Incorrect Parent Relative Paths</strong>: Fixes parent.relativePath that point to non-existent POMs by searching the project structure</li>
 *   <li><strong>.mvn Directory Creation</strong>: Creates .mvn directory in root when not upgrading to 4.1.0 to avoid root directory warnings</li>
 * </ul>
 *
 * <h3>Plugin Upgrades</h3>
 * When {@code --plugins} option is enabled (or by default), upgrades plugins known to fail with Maven 4:
 * <ul>
 *   <li><strong>maven-exec-plugin</strong>: Upgrades to version 3.2.0 or higher</li>
 *   <li><strong>maven-enforcer-plugin</strong>: Upgrades to version 3.0.0 or higher</li>
 *   <li><strong>flatten-maven-plugin</strong>: Upgrades to version 1.2.7 or higher</li>
 *   <li><strong>maven-shade-plugin</strong>: Upgrades to version 3.5.0 or higher</li>
 *   <li><strong>maven-remote-resources-plugin</strong>: Upgrades to version 3.0.0 or higher</li>
 * </ul>
 * Plugin versions are upgraded in both {@code <build><plugins>} and {@code <build><pluginManagement><plugins>} sections.
 * If a plugin version is defined via a property, the property value is updated instead.
 *
 * <h3>Inference Optimizations (Optional)</h3>
 * When {@code --infer} option is enabled, applies inference optimizations to remove redundant information:
 *
 * <h4>Limited Inference for 4.0.0 Models (Maven 3.x POMs)</h4>
 * <ul>
 *   <li><strong>Child GroupId Removal</strong>: Removes child {@code <groupId>} when it matches parent groupId</li>
 *   <li><strong>Child Version Removal</strong>: Removes child {@code <version>} when it matches parent version</li>
 * </ul>
 *
 * <h4>Full Inference for 4.1.0+ Models</h4>
 * <ul>
 *   <li><strong>ModelVersion Removal</strong>: Removes {@code <modelVersion>} element (inference enabled)</li>
 *   <li><strong>Root Attribute</strong>: Adds {@code root="true"} attribute to root project</li>
 *   <li><strong>Parent Element Trimming</strong>:
 *     <ul>
 *       <li>Removes parent {@code <groupId>} when child has no explicit groupId</li>
 *       <li>Removes parent {@code <version>} when child has no explicit version</li>
 *       <li>Removes parent {@code <artifactId>} when it can be inferred from relativePath</li>
 *     </ul>
 *   </li>
 *   <li><strong>Managed Dependencies Cleanup</strong>: Removes managed dependencies pointing to project artifacts</li>
 *   <li><strong>Dependency Inference</strong>:
 *     <ul>
 *       <li>Removes dependency {@code <version>} when it points to a project artifact</li>
 *       <li>Removes dependency {@code <groupId>} when it points to a project artifact</li>
 *       <li>Applies to main dependencies, profile dependencies, and plugin dependencies</li>
 *     </ul>
 *   </li>
 *   <li><strong>Subprojects List Removal</strong>: Removes redundant {@code <subprojects>} lists that match direct child directories</li>
 * </ul>
 *
 * <h3>Multi-Module Project Support</h3>
 * <ul>
 *   <li><strong>POM Discovery</strong>: Recursively discovers all POM files in the project structure</li>
 *   <li><strong>GAV Resolution</strong>: Computes GroupId, ArtifactId, Version for all project artifacts with parent inheritance</li>
 *   <li><strong>Cross-Module Inference</strong>: Uses knowledge of all project artifacts for intelligent inference decisions</li>
 *   <li><strong>RelativePath Resolution</strong>: Resolves parent POMs via relativePath for artifactId inference</li>
 * </ul>
 *
 * <h3>Format Preservation</h3>
 * <ul>
 *   <li><strong>Whitespace Preservation</strong>: Maintains original formatting when removing elements</li>
 *   <li><strong>Comment Preservation</strong>: Preserves XML comments and processing instructions</li>
 *   <li><strong>Line Separator Handling</strong>: Uses system-appropriate line separators</li>
 * </ul>
 */
public abstract class AbstractUpgradeGoal implements Goal {

    private final StrategyOrchestrator orchestrator;

    @Inject
    public AbstractUpgradeGoal(StrategyOrchestrator orchestrator) {
        this.orchestrator = orchestrator;
    }

    /**
     * Executes the upgrade goal.
     * Template method that calls doUpgrade and optionally saves modifications.
     */
    @Override
    public int execute(UpgradeContext context) throws Exception {
        UpgradeOptions options = context.options();

        // Determine target model version
        // Default to 4.0.0 unless --all is specified or explicit --model-version is provided
        String targetModel;
        if (options.modelVersion().isPresent()) {
            targetModel = options.modelVersion().get();
        } else if (options.all().orElse(false)) {
            targetModel = MODEL_VERSION_4_1_0;
        } else {
            targetModel = UpgradeConstants.ModelVersions.MODEL_VERSION_4_0_0;
        }

        if (!ModelVersionUtils.isValidModelVersion(targetModel)) {
            context.failure("Invalid target model version: " + targetModel);
            context.failure("Supported versions: 4.0.0, 4.1.0");
            return 1;
        }

        // Discover POMs
        context.info("Discovering POM files...");
        Path startingDirectory = options.directory().map(Paths::get).orElse(context.invokerRequest.cwd());

        Map<Path, Document> pomMap;
        try {
            pomMap = PomDiscovery.discoverPoms(startingDirectory);
        } catch (IOException | JDOMException e) {
            context.failure("Failed to discover POM files: " + e.getMessage());
            return 1;
        }

        if (pomMap.isEmpty()) {
            context.warning("No POM files found in " + startingDirectory);
            return 0;
        }

        context.info("Found " + pomMap.size() + " POM file(s)");

        // Perform the upgrade logic
        int result = doUpgrade(context, targetModel, pomMap);

        // Save modifications if this is an apply goal
        if (shouldSaveModifications() && result == 0) {
            saveModifications(context, pomMap);
        }

        return result;
    }

    /**
     * Performs the upgrade logic using the strategy pattern.
     * Delegates to StrategyOrchestrator for coordinated strategy execution.
     */
    protected int doUpgrade(UpgradeContext context, String targetModel, Map<Path, Document> pomMap) {
        // Execute strategies using the orchestrator
        try {
            UpgradeResult result = orchestrator.executeStrategies(context, pomMap);

            // Create .mvn directory if needed to avoid root directory warnings
            // This is needed for both 4.0.0 and 4.1.0 to help Maven find the project root
            createMvnDirectoryIfNeeded(context);

            return result.success() ? 0 : 1;
        } catch (Exception e) {
            context.failure("Strategy execution failed: " + e.getMessage());
            return 1;
        }
    }

    /**
     * Determines whether modifications should be saved to disk.
     * Apply goals return true, Check goals return false.
     */
    protected abstract boolean shouldSaveModifications();

    /**
     * Saves the modified documents to disk.
     */
    protected void saveModifications(UpgradeContext context, Map<Path, Document> pomMap) {
        context.info("");
        context.info("Saving modified POMs...");

        for (Map.Entry<Path, Document> entry : pomMap.entrySet()) {
            Path pomPath = entry.getKey();
            Document document = entry.getValue();
            try {
                String content = Files.readString(entry.getKey(), StandardCharsets.UTF_8);
                int startIndex = content.indexOf("<" + document.getRootElement().getName());
                String head = startIndex >= 0 ? content.substring(0, startIndex) : "";
                String lastTag = document.getRootElement().getName() + ">";
                int endIndex = content.lastIndexOf(lastTag);
                String tail = endIndex >= 0 ? content.substring(endIndex + lastTag.length()) : "";
                Format format = Format.getRawFormat();
                format.setLineSeparator(System.lineSeparator());
                XMLOutputter out = new XMLOutputter(format);
                ByteArrayOutputStream output = new ByteArrayOutputStream();
                try (OutputStream outputStream = output) {
                    outputStream.write(head.getBytes(StandardCharsets.UTF_8));
                    out.output(document.getRootElement(), outputStream);
                    outputStream.write(tail.getBytes(StandardCharsets.UTF_8));
                }
                String newBody = output.toString(StandardCharsets.UTF_8);
                Files.writeString(pomPath, newBody, StandardCharsets.UTF_8);
            } catch (Exception e) {
                context.failure("Failed to save " + pomPath + ": " + e.getMessage());
            }
        }
    }

    /**
     * Creates .mvn directory in the root directory if it doesn't exist and the model isn't upgraded to 4.1.0.
     * This avoids the warning about not being able to find the root directory.
     */
    protected void createMvnDirectoryIfNeeded(UpgradeContext context) {
        context.info("");
        context.info("Creating .mvn directory if needed to avoid root directory warnings...");

        // Find the root directory (starting directory)
        Path startingDirectory = context.options().directory().map(Paths::get).orElse(context.invokerRequest.cwd());

        Path mvnDir = startingDirectory.resolve(MVN_DIRECTORY);

        try {
            if (!Files.exists(mvnDir)) {
                if (shouldSaveModifications()) {
                    Files.createDirectories(mvnDir);
                    context.success("Created .mvn directory at " + mvnDir);
                } else {
                    context.action("Would create .mvn directory at " + mvnDir);
                }
            } else {
                context.success(".mvn directory already exists at " + mvnDir);
            }
        } catch (Exception e) {
            context.failure("Failed to create .mvn directory: " + e.getMessage());
        }
    }
}