Merge branch 'aspect' into splc23-views

Author: pmbittner

src/main/java/org/variantsync/diffdetective/experiments/views/Main.java

@@ -8,14 +8,18 @@
 import org.variantsync.diffdetective.datasets.Repository;
 import org.variantsync.diffdetective.variation.diff.filter.DiffTreeFilter;
 import org.variantsync.diffdetective.variation.diff.parse.DiffTreeParseOptions;
-import org.variantsync.diffdetective.variation.tree.view.query.ArtifactQuery;
+import org.variantsync.diffdetective.variation.tree.view.relevance.Search;
 
 import java.io.IOException;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Main entry point for running the feasibility study (Section 6) of our SPLC'23 paper
+ * Views on Edits to Variational Software.
+ */
 public class Main {
     /*
      * There is a bug in DiffView::naive when ignoreEmptyLines is set to true under
@@ -24,19 +28,25 @@ public class Main {
      * commit: 2254b6c09cff8f3a83684fd159289d0e305b0e7d
      * patch: "src/alloc.c"
      * view_naive
-     * with the following query.
+     * with the following relevance.
      * What is weird that the parsing only failed when running the analyses but not when extracting the diff to a unit
      * test and parsing it there.
      * Maybe it has something to do with linebreak or whitespace characters?
      */
-    private static final ArtifactQuery bugQuery = new ArtifactQuery("  /* Check both of the above conditions, for symbols.  */");
+    private static final Search bugRelevance = new Search("  /* Check both of the above conditions, for symbols.  */");
     public static DiffTreeParseOptions DIFFTREE_PARSE_OPTIONS =
             new DiffTreeParseOptions(
                     true,
                     false
             );
 
-    public static Analysis AnalysisFactory(Repository repo, Path repoOutputDir) {
+    /**
+     * Creates the analysis to perform on the given repository to run our feasibility study.
+     * @param repo The repository to run the feasibility study on.
+     * @param repoOutputDir The directory to which output should be written.
+     * @return The analysis to run.
+     */
+    private static Analysis AnalysisFactory(Repository repo, Path repoOutputDir) {
         return new Analysis(
                 "Views Analysis",
                 new ArrayList<>(List.of(
@@ -51,6 +61,11 @@ public static Analysis AnalysisFactory(Repository repo, Path repoOutputDir) {
         );
     }
 
+    /**
+     * Main method for running the feasibility study (Section 6).
+     * @param args see {@link AnalysisRunner.Options#DEFAULT(String[])}
+     * @throws IOException When an IO operation within the feasibility study fails.
+     */
     public static void main(String[] args) throws IOException {
         final AnalysisRunner.Options defaultOptions = AnalysisRunner.Options.DEFAULT(args);
         final AnalysisRunner.Options analysisOptions = new AnalysisRunner.Options(

src/main/java/org/variantsync/diffdetective/experiments/views/ViewAnalysis.java

@@ -2,22 +2,46 @@
 
 import org.variantsync.diffdetective.util.CSV;
 import org.variantsync.diffdetective.variation.diff.DiffTree;
-import org.variantsync.diffdetective.variation.tree.view.query.Query;
-import org.variantsync.diffdetective.variation.tree.view.query.VariantQuery;
+import org.variantsync.diffdetective.variation.diff.view.DiffView;
+import org.variantsync.diffdetective.variation.tree.view.relevance.Relevance;
+import org.variantsync.diffdetective.variation.tree.view.relevance.Configure;
 
 import static org.variantsync.functjonal.Functjonal.intercalate;
 
+/**
+ * Single data point in our feasibility study.
+ * An object of this class corresponds to a row in the CSV files we export.
+ * This row contains all information for benchmarking a single view generation:
+ * @param commit The commit on which views were generated.
+ * @param file The file of the patch that was analysed.
+ * @param relevance The relevance predicate from which the views were generated.
+ * @param msNaive Milliseconds it took to generate the view with the {@link DiffView#naive(DiffTree, Relevance) naive algorithm}
+ * @param msOptimized Milliseconds it took to generate the view with the {@link DiffView#optimized(DiffTree, Relevance) optimized algorithm}
+ * @param diffStatistics Various statistics on the variation diff of the analysed patch. 
+ * @param viewStatistics The same statistics as for the original variation diff but for the produced view.
+ */
 public record ViewEvaluation(
 //        Repository repo,
         String commit,
         String file,
-        Query query,
+        Relevance relevance,
         long msNaive,
         long msOptimized,
         DiffStatistics diffStatistics,
         DiffStatistics viewStatistics
 ) implements CSV {
+    /**
+     * Holds various information of a variation diff.
+     * @param nodeCount The number of nodes contained in the variation diff.
+     * @param annotationNodeCount The number of annotation nodes in the variation diff.
+     */
     public record DiffStatistics(int nodeCount, int annotationNodeCount) {
+        /**
+         * Gathers statistics of a given variation diff.
+         * This method is side-effect free and will not alter the given diff.
+         * @param d A variation diff to extract statistics from.
+         * @return The extracted statistics.
+         */
         public static DiffStatistics of(final DiffTree d) {
             final int[] nodeCount = {0};
             final int[] annotationNodeCount = {0};
@@ -33,6 +57,13 @@ public static DiffStatistics of(final DiffTree d) {
         }
     }
 
+    /**
+     * Creates the header for a CSV file in which objects of this class
+     * can be rows.
+     * @param delimiter The delimiter to use between rows in the CSV file (see {@link CSV#DEFAULT_CSV_DELIMITER}.
+     * @return A string that should be the first row in a CSV file with objects of this class
+     *         as rows.
+     */
     public static String makeHeader(String delimiter) {
         return intercalate(delimiter,
 //                "repository",
@@ -55,7 +86,7 @@ public String toCSV(String delimiter) {
 //                repo.getRepositoryName(),
                 commit,
                 file,
-                query.getFunctionName(),
+                relevance.getFunctionName(),
 //                getQueryArguments(),
                 msNaive,
                 msOptimized,
@@ -65,11 +96,4 @@ public String toCSV(String delimiter) {
                 viewStatistics.annotationNodeCount
         );
     }
-
-    private String getQueryArguments() {
-        if (query instanceof VariantQuery) {
-            return query.parametersToString();
-        }
-        return "";
-    }
 }

src/main/java/org/variantsync/diffdetective/experiments/views/result/ViewEvaluation.java

@@ -13,8 +13,8 @@
 
 /**
  * Class to fix bugs related to {@link True} and {@link False} of FeatureIDE.
- * See: https://github.com/FeatureIDE/FeatureIDE/issues/1111
- * See: https://github.com/FeatureIDE/FeatureIDE/issues/1333
+ * See: <a href="https://github.com/FeatureIDE/FeatureIDE/issues/1111">FeatureIDE Issue 1111</a>
+ * See: <a href="https://github.com/FeatureIDE/FeatureIDE/issues/1333">FeatureIDE Issue 1333</a>
  *
  * This class contains constants for representing atomic values true and false in formulas
  * as well as a conversion method for parsing certain feature names to true and false, respectively.