refactor: improve the source tracing mechanism

The new mechanism is more flexible and provides more introspection
capabilities. Furthermore, it provides more documentation about the
intent of our source tracking.

Author: ibbem

src/main/java/org/variantsync/diffdetective/diff/git/GitPatch.java

@@ -1,17 +1,19 @@
 package org.variantsync.diffdetective.diff.git;
 
+import java.util.List;
+
 import org.eclipse.jgit.diff.DiffEntry;
 import org.variantsync.diffdetective.diff.text.TextBasedDiff;
+import org.variantsync.diffdetective.util.Source;
 import org.variantsync.diffdetective.variation.diff.Time;
 import org.variantsync.diffdetective.variation.diff.VariationDiff; // For Javadoc
-import org.variantsync.diffdetective.variation.diff.source.VariationDiffSource;
 
 /**
  * Interface for patches from a git repository.
  * A git patch is a {@link TextBasedDiff} from which {@link VariationDiff}s can be created.
  *
  */
-public interface GitPatch extends VariationDiffSource, TextBasedDiff {
+public interface GitPatch extends Source, TextBasedDiff {
     /**
      * Minimal default implementation of {@link GitPatch}
      * @param getDiff The diff in text form.
@@ -41,6 +43,16 @@ public GitPatch shallowClone() {
         public String toString() {
             return oldFileName + "@ " + getParentCommitHash + " (parent) to " + newFileName + " @ " + getCommitHash + " (child)";
         }
+
+        @Override
+        public String getSourceExplanation() {
+            return "SimpleGitPatch";
+        }
+
+        @Override
+        public List<Object> getSourceArguments() {
+            return List.of(getChangeType(), oldFileName(), newFileName(), getCommitHash(), getParentCommitHash());
+        }
     }
 
     /**

src/main/java/org/variantsync/diffdetective/diff/git/PatchDiff.java

@@ -123,4 +123,9 @@ public String toString() {
     public GitPatch shallowClone() {
         return new GitPatch.SimpleGitPatch(getDiff(), getChangeType(), getFileName(Time.BEFORE), getFileName(Time.AFTER), getCommitHash(), getParentCommitHash());
     }
+
+    @Override
+    public String getSourceExplanation() {
+        return "PatchDiff";
+    }
 }

src/main/java/org/variantsync/diffdetective/examplesearch/ExampleFinder.java

@@ -11,6 +11,7 @@
 import org.variantsync.diffdetective.show.Show;
 import org.variantsync.diffdetective.util.Assert;
 import org.variantsync.diffdetective.util.IO;
+import org.variantsync.diffdetective.util.Source;
 import org.variantsync.diffdetective.util.StringUtils;
 import org.variantsync.diffdetective.variation.DiffLinesLabel;
 import org.variantsync.diffdetective.variation.diff.Time;
@@ -24,7 +25,6 @@
 import org.variantsync.diffdetective.variation.diff.serialize.edgeformat.DefaultEdgeLabelFormat;
 import org.variantsync.diffdetective.variation.diff.serialize.nodeformat.MappingsDiffNodeFormat;
 import org.variantsync.diffdetective.variation.diff.serialize.treeformat.CommitDiffVariationDiffLabelFormat;
-import org.variantsync.diffdetective.variation.diff.source.VariationDiffSource;
 
 import java.io.IOException;
 import java.nio.file.Path;
@@ -110,8 +110,8 @@ private boolean checkIfExample(Analysis analysis, String localDiff) {
             // Not every local diff can be parsed to a VariationDiff because diffs are unaware of the underlying language (i.e., CPP).
             // We want only running examples whose diffs describe entire diff trees for easier understanding.
             if (isGoodExample.test(localTree)) {
-                Assert.assertTrue(variationDiff.getSource() instanceof GitPatch);
-                final GitPatch variationDiffSource = (GitPatch) variationDiff.getSource();
+                GitPatch variationDiffSource = Source.findFirst(variationDiff, GitPatch.class);
+                Assert.assertNotNull(variationDiffSource);
                 localTree.setSource(variationDiffSource.shallowClone());
             } else {
                 return false;
@@ -149,9 +149,9 @@ public boolean analyzeVariationDiff(Analysis analysis) {
     }
 
     private void exportExample(final Analysis analysis, final String tdiff, final VariationDiff<DiffLinesLabel> vdiff, Path outputDir) {
-        Assert.assertTrue(vdiff.getSource() instanceof GitPatch);
         final Repository repo = analysis.getRepository();
-        final GitPatch patch = (GitPatch) vdiff.getSource();
+        final GitPatch patch = Source.findFirst(vdiff, GitPatch.class);
+        Assert.assertNotNull(patch);
         outputDir = outputDir.resolve(Path.of(repo.getRepositoryName() + "_" + patch.getCommitHash()));
         final String filename = patch.getFileName(Time.AFTER);
 
@@ -185,8 +185,8 @@ private void exportExample(final Analysis analysis, final String tdiff, final Va
     }
 
     static String getDiff(final VariationDiff<?> tree) {
-        final VariationDiffSource source = tree.getSource();
-        Assert.assertTrue(source instanceof TextBasedDiff);
-        return ((TextBasedDiff) source).getDiff();
+        TextBasedDiff textBasedDiff = Source.findFirst(tree, TextBasedDiff.class);
+        Assert.assertNotNull(textBasedDiff);
+        return textBasedDiff.getDiff();
     }
 }

src/main/java/org/variantsync/diffdetective/experiments/thesis_es/UnparseAnalysis.java

@@ -9,6 +9,7 @@
 import org.variantsync.diffdetective.util.CSV;
 import org.variantsync.diffdetective.util.FileUtils;
 import org.variantsync.diffdetective.util.IO;
+import org.variantsync.diffdetective.util.Source;
 import org.variantsync.diffdetective.util.StringUtils;
 import org.variantsync.diffdetective.variation.DiffLinesLabel;
 import org.variantsync.diffdetective.variation.VariationUnparser;
@@ -17,7 +18,6 @@
 import org.variantsync.diffdetective.variation.diff.construction.JGitDiff;
 import org.variantsync.diffdetective.variation.diff.parse.VariationDiffParseOptions;
 import org.variantsync.diffdetective.variation.tree.VariationTree;
-import org.variantsync.diffdetective.variation.tree.source.VariationTreeSource;
 
 public class UnparseAnalysis implements Analysis.Hooks {
 
@@ -215,7 +215,7 @@ public static String removeWhitespace(String string, boolean diff) {
     public static String parseUnparseTree(String text, VariationDiffParseOptions option) {
         String temp = "b";
         try {
-            VariationTree<DiffLinesLabel> tree = VariationTree.fromText(text, VariationTreeSource.Unknown, option);
+            VariationTree<DiffLinesLabel> tree = VariationTree.fromText(text, Source.Unknown, option);
             temp = VariationUnparser.unparseTree(tree);
         } catch (Exception e) {
             e.printStackTrace();

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

@@ -85,8 +85,8 @@ public String toCSV(String delimiter) {
 //                repo.getRepositoryName(),
                 commit,
                 file,
-                relevance.getFunctionName(),
-//                getQueryArguments(),
+                relevance.getSourceExplanation(),
+//                relevance.getSourceArguments(),
                 msNaive,
                 msOptimized,
                 diffStatistics.nodeCount,

src/main/java/org/variantsync/diffdetective/mining/RWCompositePatternTreeFormat.java

@@ -1,22 +1,25 @@
 package org.variantsync.diffdetective.mining;
 
-import org.variantsync.diffdetective.variation.diff.source.VariationDiffSource;
+import java.util.List;
+
+import org.variantsync.diffdetective.util.FileSource;
+import org.variantsync.diffdetective.util.Source;
 import org.variantsync.diffdetective.variation.diff.serialize.treeformat.VariationDiffLabelFormat;
-import org.variantsync.diffdetective.variation.diff.source.PatchFile;
 
 public class RWCompositePatternTreeFormat implements VariationDiffLabelFormat {
     @Override
-    public VariationDiffSource fromLabel(String label) {
+    public Source fromLabel(String label) {
         throw new UnsupportedOperationException("Cannot read");
     }
 
     @Override
-    public String toLabel(VariationDiffSource variationDiffSource) {
-        if (variationDiffSource instanceof PatchFile p) {
-            final String fileName = p.path().getFileName().toString();
-            return fileName.substring(0, fileName.indexOf('.')).replaceAll("_", " ");
+    public String toLabel(Source variationDiffSource) {
+        List<FileSource> pathSources = Source.findAll(variationDiffSource, FileSource.class);
+        if (pathSources.size() != 1) {
+            throw new IllegalArgumentException("Expected a single path source but got:\n" + Source.fullExplanation(variationDiffSource));
         }
 
-        throw new IllegalArgumentException("Expected a PatchFile but got " + variationDiffSource);
+        final String fileName = pathSources.get(0).getPath().getFileName().toString();
+        return fileName.substring(0, fileName.indexOf('.')).replaceAll("_", " ");
     }
 }

src/main/java/org/variantsync/diffdetective/show/Show.java

@@ -6,6 +6,7 @@
 import org.variantsync.diffdetective.show.engine.GameEngine;
 import org.variantsync.diffdetective.show.engine.geom.Vec2;
 import org.variantsync.diffdetective.show.variation.VariationDiffApp;
+import org.variantsync.diffdetective.util.Source;
 import org.variantsync.diffdetective.variation.Label;
 import org.variantsync.diffdetective.variation.diff.DiffNode;
 import org.variantsync.diffdetective.variation.diff.VariationDiff;
@@ -30,7 +31,7 @@ public static GameEngine diff(final VariationDiff<?> d, final String title) {
     }
 
     public static GameEngine diff(final VariationDiff<?> d) {
-        return diff(d, d.getSource().toString());
+        return diff(d, Source.shortExplanation(d));
     }
 
     public static <L extends Label> GameEngine tree(final VariationTree<L> t, final String title, List<DiffNodeLabelFormat<L>> availableFormats) {
@@ -47,7 +48,7 @@ public static GameEngine tree(final VariationTree<?> t, final String title) {
     }
 
     public static GameEngine tree(final VariationTree<?> t) {
-        return tree(t, t.source().toString());
+        return tree(t, Source.shortExplanation(t));
     }
 
     public static <L extends Label> GameEngine baddiff(final BadVDiff<L> badVDiff, final String title, List<DiffNodeLabelFormat<L>> availableFormats) {
@@ -80,6 +81,6 @@ public static GameEngine baddiff(final BadVDiff<?> badVDiff, final String title)
     }
 
     public static GameEngine baddiff(final BadVDiff<?> badVDiff) {
-        return baddiff(badVDiff, badVDiff.diff().source().toString());
+        return baddiff(badVDiff, Source.shortExplanation(badVDiff.diff()));
     }
 }

src/main/java/org/variantsync/diffdetective/util/CompositeSource.java

@@ -0,0 +1,36 @@
+package org.variantsync.diffdetective.util;
+
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Represents a {@link Source} without arguments.
+ */
+public class CompositeSource implements Source {
+    private final String sourceExplanation;
+    private final List<Source> sources;
+
+    /**
+     * @param sourceExplanation is returned verbatim by {@link getSourceExplanation}
+     * @param sources is returned as immutable list by {@link getSources}
+     */
+    public CompositeSource(String sourceExplanation, Source... sources) {
+        this.sourceExplanation = sourceExplanation;
+        this.sources = Arrays.asList(sources);
+    }
+
+    @Override
+    public String getSourceExplanation() {
+        return sourceExplanation;
+    }
+
+    @Override
+    public List<Source> getSources() {
+        return sources;
+    }
+
+    @Override
+    public String toString() {
+        return Source.shallowExplanation(this);
+    }
+}

src/main/java/org/variantsync/diffdetective/util/FileSource.java

@@ -0,0 +1,19 @@
+package org.variantsync.diffdetective.util;
+
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * Represents a file input in a {@link Source} hierarchy.
+ */
+public record FileSource(Path getPath) implements Source {
+    @Override
+    public String getSourceExplanation() {
+        return "File";
+    }
+
+    @Override
+    public List<Object> getSourceArguments() {
+        return List.of(getPath());
+    }
+}