feat: add --preview flag to preview aviator remediations before applying

fcli-core/fcli-aviator-common/src/main/java/com/fortify/cli/aviator/_common/cli/mixin/AbstractApplyRemediationsOptionsMixin.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2021-2026 Open Text.
+ *
+ * The only warranties for products and services of Open Text
+ * and its affiliates and licensors ("Open Text") are as may
+ * be set forth in the express warranty statements accompanying
+ * such products and services. Nothing herein should be construed
+ * as constituting an additional warranty. Open Text shall not be
+ * liable for technical or editorial errors or omissions contained
+ * herein. The information contained herein is subject to change
+ * without notice.
+ */
+package com.fortify.cli.aviator._common.cli.mixin;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+import org.apache.commons.lang3.StringUtils;
+
+import com.fortify.cli.aviator._common.remediations_cache.IApplyRemediationsOptions;
+import com.fortify.cli.common.exception.FcliSimpleException;
+
+import lombok.Getter;
+import picocli.CommandLine.Option;
+
+/**
+ * Abstract base for apply-remediations options. Provides shared CLI options and validation template method.
+ * Product-specific subclasses declare source-selection mixins and implement validation hooks.
+ */
+@Getter
+public abstract class AbstractApplyRemediationsOptionsMixin implements IApplyRemediationsOptions {
+    @Option(names = {"--source-dir"})
+    private String sourceCodeDirectory = System.getProperty("user.dir");
+
+    @Option(names = {"--issue-ids"}, split = ",")
+    private List<String> issueIds;
+
+    @Option(names = {"--preview"})
+    private boolean previewMode = false;
+
+    /**
+     * Validates all options by calling validation hooks in order.
+     * Template method: ensures consistent validation sequence across SSC and FoD.
+     */
+    @Override
+    public final void validate() {
+        validateSourceSelection();
+        validateSourceDir();
+        validateIssueIdsConstraints();
+    }
+
+    /** Hook for product-specific source selection validation (--from-cache vs online selection). */
+    protected abstract void validateSourceSelection();
+
+    /** Hook to determine if --from-cache is selected (needed for --issue-ids constraint validation). */
+    protected abstract boolean isCacheMode();
+
+    private void validateSourceDir() {
+        FcliSimpleException.throwIf(
+                StringUtils.isBlank(sourceCodeDirectory),
+                "--source-dir must specify a valid directory path");
+        Path path = Path.of(sourceCodeDirectory);
+        FcliSimpleException.throwIf(
+                !Files.exists(path) || !Files.isDirectory(path),
+                "--source-dir path does not exist or is not a directory: %s", sourceCodeDirectory);
+        FcliSimpleException.throwIf(
+                !Files.isReadable(path),
+                "--source-dir path is not accessible: %s", sourceCodeDirectory);
+    }
+
+    private void validateIssueIdsConstraints() {
+        FcliSimpleException.throwIf(
+                issueIds != null && !issueIds.isEmpty() && !isCacheMode(),
+                "--issue-ids can only be used with --from-cache; "
+                        + "create a cache with download-remediations-cache and rerun with --from-cache");
+    }
+}

fcli-core/fcli-aviator-common/src/main/java/com/fortify/cli/aviator/_common/output/cli/cmd/AbstractAviatorApplyRemediationsCommand.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2021-2026 Open Text.
+ *
+ * The only warranties for products and services of Open Text
+ * and its affiliates and licensors ("Open Text") are as may
+ * be set forth in the express warranty statements accompanying
+ * such products and services. Nothing herein should be construed
+ * as constituting an additional warranty. Open Text shall not be
+ * liable for technical or editorial errors or omissions contained
+ * herein. The information contained herein is subject to change
+ * without notice.
+ */
+package com.fortify.cli.aviator._common.output.cli.cmd;
+
+import java.util.Set;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fortify.cli.aviator._common.cli.mixin.AbstractApplyRemediationsOptionsMixin;
+import com.fortify.cli.aviator._common.remediations_cache.IRemediationsFprSource;
+import com.fortify.cli.aviator._common.remediations_cache.RemediationsApplyHelper;
+import com.fortify.cli.aviator._common.remediations_cache.RemediationsApplyHelper.ApplyResult;
+import com.fortify.cli.aviator._common.util.AviatorIssueIdFilterUtils;
+import com.fortify.cli.aviator.config.AviatorLoggerImpl;
+import com.fortify.cli.common.output.cli.cmd.AbstractOutputCommand;
+import com.fortify.cli.common.output.cli.cmd.IJsonNodeSupplier;
+import com.fortify.cli.common.output.cli.mixin.OutputHelperMixins;
+import com.fortify.cli.common.progress.cli.mixin.ProgressWriterFactoryMixin;
+import com.fortify.cli.common.progress.helper.IProgressWriter;
+
+import lombok.Getter;
+import picocli.CommandLine.Mixin;
+
+/**
+ * Abstract base command for applying remediations. Orchestrates validation, FPR source acquisition,
+ * and remediation application. Product-specific subclasses provide options mixin and implement hooks.
+ */
+public abstract class AbstractAviatorApplyRemediationsCommand extends AbstractOutputCommand
+        implements IJsonNodeSupplier {
+
+    @Getter @Mixin private OutputHelperMixins.DetailsNoQuery outputHelper;
+    @Mixin private ProgressWriterFactoryMixin progressWriterFactoryMixin;
+
+    /** Subclasses declare their product-specific options mixin (SSC or FoD). */
+    protected abstract AbstractApplyRemediationsOptionsMixin getApplyOptions();
+
+    @Override
+    public final JsonNode getJsonNode() {
+        AbstractApplyRemediationsOptionsMixin applyOptions = getApplyOptions();
+        applyOptions.validate();
+        Set<String> issueIdFilter = AviatorIssueIdFilterUtils.normalizeIssueIds(applyOptions.getIssueIds());
+        try (IProgressWriter progressWriter = progressWriterFactoryMixin.create()) {
+            AviatorLoggerImpl logger = new AviatorLoggerImpl(progressWriter);
+            try (IRemediationsFprSource fprSource = openFprSource(logger, progressWriter)) {
+                ApplyResult result = RemediationsApplyHelper.apply(fprSource, applyOptions, issueIdFilter, logger);
+                return buildResultNode(fprSource, result, issueIdFilter);
+            }
+        }
+    }
+
+    protected abstract IRemediationsFprSource openFprSource(AviatorLoggerImpl logger, IProgressWriter progressWriter);
+
+    protected abstract JsonNode buildResultNode(IRemediationsFprSource fprSource, ApplyResult result, Set<String> issueIdFilter);
+
+    @Override
+    public final boolean isSingular() { return true; }
+}

fcli-core/fcli-aviator-common/src/main/java/com/fortify/cli/aviator/_common/remediations_cache/IApplyRemediationsOptions.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2021-2026 Open Text.
+ *
+ * The only warranties for products and services of Open Text
+ * and its affiliates and licensors ("Open Text") are as may
+ * be set forth in the express warranty statements accompanying
+ * such products and services. Nothing herein should be construed
+ * as constituting an additional warranty. Open Text shall not be
+ * liable for technical or editorial errors or omissions contained
+ * herein. The information contained herein is subject to change
+ * without notice.
+ */
+package com.fortify.cli.aviator._common.remediations_cache;
+
+import java.util.List;
+
+/** Abstraction over the shared apply-remediations CLI options, allowing RemediationsApplyHelper
+ *  to remain independent of concrete Picocli types. */
+public interface IApplyRemediationsOptions {
+    String getSourceCodeDirectory();
+    List<String> getIssueIds();
+    boolean isPreviewMode();
+    void validate();
+}

fcli-core/fcli-aviator-common/src/main/java/com/fortify/cli/aviator/_common/remediations_cache/RemediationsApplyHelper.java

@@ -19,8 +19,6 @@
 import java.util.List;
 import java.util.Set;
 
-import org.slf4j.Logger;
-
 import com.fortify.cli.aviator._common.exception.AviatorSimpleException;
 import com.fortify.cli.aviator._common.util.AviatorRemediationMetricsHelper;
 import com.fortify.cli.aviator.applyRemediation.ApplyAutoRemediationOnSource;
@@ -29,10 +27,13 @@
 import com.fortify.cli.aviator.util.FprHandle;
 import com.fortify.cli.common.exception.FcliTechnicalException;
 
+import lombok.extern.slf4j.Slf4j;
+
 /**
  * Single apply-remediations loop for any {@link IRemediationsFprSource}
  * (cache zip entries or online downloads). Soft-skips on {@link AviatorSimpleException}.
  */
+@Slf4j
 public final class RemediationsApplyHelper {
     private RemediationsApplyHelper() {}
 
@@ -43,22 +44,23 @@ public record ApplyResult(
             List<RemediationMetric> metrics) {}
 
     /**
-     * Applies remediations for each source entry until done or the issue-id filter is exhausted.
-     * Caller owns {@code source} lifecycle (try-with-resources).
+     * Applies or previews remediations for each FPR source entry until done or the issue-id filter is exhausted.
+     * Caller owns {@code fprSource} lifecycle (try-with-resources).
      */
     public static ApplyResult apply(
-            IRemediationsFprSource source,
-            String sourceCodeDirectory,
-            IAviatorLogger logger,
+            IRemediationsFprSource fprSource,
+            IApplyRemediationsOptions options,
             Set<String> issueIdFilter,
-            Logger skipLog) {
+            IAviatorLogger logger) {
         Accumulator acc = new Accumulator(issueIdFilter);
-        source.forEachEntry((fprPath, label, id, index, total) -> {
+        fprSource.forEachEntry((fprPath, label, id, index, total) -> {
             if (acc.remaining != null && acc.remaining.isEmpty()) {
                 return false;
             }
             RemediationMetric metric = applyOne(
-                    fprPath, label, index, total, sourceCodeDirectory, logger, acc.remaining, skipLog);
+                    fprPath, label, index, total,
+                    options.getSourceCodeDirectory(), logger, acc.remaining,
+                    options.isPreviewMode());
             if (metric == null) {
                 acc.skipped++;
             } else {
@@ -85,13 +87,13 @@ private static RemediationMetric applyOne(
             String sourceCodeDirectory,
             IAviatorLogger logger,
             Set<String> issueFilter,
-            Logger skipLog) {
+            boolean previewMode) {
         logger.progress("Processing FPR " + index + "/" + total + " (" + entryLabel + ")");
-        logger.progress("Status: Processing FPR with Aviator for Applying Auto Remediations");
+        logger.progress("Status: Processing FPR with Aviator for " + (previewMode ? "Previewing" : "Applying") + " Auto Remediations");
         try (FprHandle fprHandle = new FprHandle(fprPath)) {
-            return ApplyAutoRemediationOnSource.applyRemediations(fprHandle, sourceCodeDirectory, logger, issueFilter);
+            return ApplyAutoRemediationOnSource.applyRemediations(fprHandle, sourceCodeDirectory, logger, issueFilter, previewMode);
         } catch (AviatorSimpleException e) {
-            skipLog.warn("Skipping entry {} as {}", entryLabel, e.getMessage());
+            log.warn("Skipping entry {} as {}", entryLabel, e.getMessage());
             return null;
         } catch (IOException e) {
             throw new FcliTechnicalException("Failed to close FPR handle for entry " + entryLabel, e);

fcli-core/fcli-aviator-common/src/main/java/com/fortify/cli/aviator/_common/util/AviatorRemediationMetricsHelper.java

@@ -24,6 +24,7 @@
 import com.fasterxml.jackson.databind.node.ArrayNode;
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import com.fortify.cli.aviator.fpr.processor.RemediationProcessor.RemediationMetric;
+import com.fortify.cli.aviator.fpr.processor.preview.PreviewDetail;
 import com.fortify.cli.common.json.JsonHelper;
 import com.fortify.cli.common.output.transform.IActionCommandResultSupplier;
 
@@ -38,25 +39,49 @@ private AviatorRemediationMetricsHelper() {}
      * aggregation (XML totals); non-null selects filtered aggregation (requested IDs).
      */
     public static RemediationMetric aggregateMetrics(Set<String> requestedIssueIds, Collection<RemediationMetric> metrics) {
+        Collection<RemediationMetric> safeMetrics = metrics == null ? List.of() : metrics;
+        return requestedIssueIds == null
+                ? aggregateUnfiltered(safeMetrics)
+                : aggregateFiltered(requestedIssueIds, safeMetrics);
+    }
+
+    private static RemediationMetric aggregateUnfiltered(Collection<RemediationMetric> metrics) {
+        int totalRemediations = 0, appliedRemediations = 0;
         Set<String> modifiedFiles = new LinkedHashSet<>();
         Map<String, Integer> skippedByReason = new LinkedHashMap<>();
-        Collection<RemediationMetric> safeMetrics = metrics == null ? List.of() : metrics;
-        if (requestedIssueIds == null) {
-            int totalRemediations = 0;
-            int appliedRemediations = 0;
-            for (RemediationMetric metric : safeMetrics) {
-                totalRemediations += metric.totalRemediations();
-                appliedRemediations += metric.appliedRemediations();
-                accumulateFilesAndSkips(metric, modifiedFiles, skippedByReason);
+        List<PreviewDetail> previewDetails = new ArrayList<>();
+        boolean previewMode = false;
+        for (RemediationMetric metric : metrics) {
+            totalRemediations += metric.totalRemediations();
+            appliedRemediations += metric.appliedRemediations();
+            accumulateFilesAndSkips(metric, modifiedFiles, skippedByReason);
+            if (metric instanceof RemediationMetric.Preview preview) {
+                previewMode = true;
+                previewDetails.addAll(preview.previewDetails());
             }
-            return RemediationMetric.unfiltered(totalRemediations, appliedRemediations, modifiedFiles, skippedByReason);
         }
+        return previewMode
+                ? RemediationMetric.previewUnfiltered(totalRemediations, appliedRemediations, modifiedFiles, skippedByReason, previewDetails)
+                : RemediationMetric.unfiltered(totalRemediations, appliedRemediations, modifiedFiles, skippedByReason);
+    }
+
+    private static RemediationMetric aggregateFiltered(Set<String> requestedIssueIds, Collection<RemediationMetric> metrics) {
         Set<String> appliedIssueIds = new LinkedHashSet<>();
-        for (RemediationMetric metric : safeMetrics) {
+        Set<String> modifiedFiles = new LinkedHashSet<>();
+        Map<String, Integer> skippedByReason = new LinkedHashMap<>();
+        List<PreviewDetail> previewDetails = new ArrayList<>();
+        boolean previewMode = false;
+        for (RemediationMetric metric : metrics) {
             appliedIssueIds.addAll(metric.appliedIssueIds());
             accumulateFilesAndSkips(metric, modifiedFiles, skippedByReason);
+            if (metric instanceof RemediationMetric.Preview preview) {
+                previewMode = true;
+                previewDetails.addAll(preview.previewDetails());
+            }
         }
-        return RemediationMetric.filtered(requestedIssueIds, appliedIssueIds, modifiedFiles, skippedByReason);
+        return previewMode
+                ? RemediationMetric.previewFiltered(requestedIssueIds, appliedIssueIds, modifiedFiles, skippedByReason, previewDetails)
+                : RemediationMetric.filtered(requestedIssueIds, appliedIssueIds, modifiedFiles, skippedByReason);
     }
 
     private static void accumulateFilesAndSkips(
@@ -92,7 +117,12 @@ public static String formatSkippedReasons(Map<String, Integer> skippedByReason)
     }
 
     public static String actionLabel(RemediationMetric metric) {
-        return metric != null && metric.appliedRemediations() > 0 ? "Remediation-Applied" : "No-Remediation-Applied";
+        boolean previewMode = metric instanceof RemediationMetric.Preview;
+        if (metric != null && metric.appliedRemediations() > 0) {
+            return previewMode ? "Remediation-Previewed" : "Remediation-Applied";
+        } else {
+            return previewMode ? "No-Remediation-Previewed" : "No-Remediation-Applied";
+        }
     }
 
     public static String na(String value) {
@@ -118,10 +148,22 @@ public static void putRemediationMetricFields(ObjectNode result, RemediationMetr
         result.set("modifiedFiles", toArrayNode(modifiedFiles));
     }
 
-    /** Metric fields plus {@code __action__} (shared by SSC/FoD result builders). */
+    /** Metric fields plus {@code __action__} and, for preview results, preview details (shared by SSC/FoD result builders). */
     public static void putMetricAndAction(ObjectNode result, RemediationMetric metric) {
         putRemediationMetricFields(result, metric);
         result.put(IActionCommandResultSupplier.actionFieldName, actionLabel(metric));
+
+        if (metric instanceof RemediationMetric.Preview preview) {
+            result.set("previewDetails", toPreviewDetailsArray(preview.previewDetails()));
+        }
+    }
+
+    private static ArrayNode toPreviewDetailsArray(List<?> previewDetails) {
+        ArrayNode array = JsonHelper.getObjectMapper().createArrayNode();
+        if (previewDetails != null) {
+            previewDetails.forEach(detail -> array.add(JsonHelper.getObjectMapper().valueToTree(detail)));
+        }
+        return array;
     }
 
     /**