Merge branch 'develop' into fix-configure

Author: pmbittner

README.md

@@ -10,7 +10,7 @@
 
 DiffDetective is an open-source Java library for variability-aware source code differencing and the **analysis of version histories of software product lines**. This means that DiffDetective can **turn a generic differencer into a variability-aware differencer** by means of a pre- or post-processing. DiffDetective is centered around **formally verified** data structures for variability (variation trees) and variability-aware diffs (variation diffs). These data structures are **generic**, and DiffDetective currently implements **C preprocessor support** to parse respective annotations when used to implement variability. The picture below depicts the process of variability-aware differencing.
 
-<img alt="Variability-Aware Differencing Overview" src="docs/teaser.png" height="500" />
+<img alt="Variability-Aware Differencing Overview" src="docs/variability-aware-differencing.png" height="500" />
 
 Given two states of a C-preprocessor annotated source code file (left), for example before and after a commit, DiffDetective constructs a variability-aware diff (right) that distinguishes changes to source code from changes to variability annotations. DiffDetective can construct such a variation diff either, by first using a generic differencer, and separating the information (center path), or by first parsing both input versions to an abstract representation, a variation tree (center top and bottom), and constructing a variation diff using a tree differencing algorithm in a second step.
 
@@ -80,6 +80,18 @@ Additionally, there is a screencast available on YouTube, guiding you through th
 [![DiffDetective Demonstration](docs/yt_thumbnail.png)](https://www.youtube.com/watch?v=q6ight5EDQY)
 
 
+## Supported Differencing Algorithms
+
+In principle, any generic differencing algorithm (i.e, any algorithm that may operate on text or trees) can be made variability-aware with DiffDetective, as explained in our demo paper (see below). Some algorithms are integrated directly in the DiffDetective library, while others come as additional Maven projects.
+
+### Shipped with DiffDetective
+- Git Diff as implemented by [JGit](https://github.com/eclipse-jgit/jgit)
+- [GumTree](https://github.com/GumTreeDiff/gumtree), and all algorithms and matching engines supported by the GumTree library
+
+### Extra Modules
+- [TrueDiff](https://gitlab.rlp.net/plmz/truediff): Support for TrueDiff comes as [a separate Maven project](https://github.com/VariantSync/TrueDiffDetective).
+
+
 ## Publications
 
 ### Variability-Aware Differencing with DiffDetective (FSE 2024, ⭐ [Best Demo Paper](https://2024.esec-fse.org/info/awards) ⭐)
@@ -167,9 +179,10 @@ Edge-typed variation diffs and the replication package are implemented in a fork
 
 DiffDetective was extended and used within bachelor's and master's theses:
 
+- _Unparsing von Datenstrukturen zur Analyse von C-Präprozessor-Variabilität_, Eugen Shulimov, Bachelor's Thesis, 2025, [DOI 10.17619/UNIPB/1-2385](http://doi.org/10.17619/UNIPB/1-2385), (german): Eugen added an unparser for variation trees, essentially inverting the horizontal arrows in our commuting diagram at the top of this README file. The unparser for variation diffs reuses the unparser for variation trees by projecting a variation diff to its two variation trees (before and after the change), unparsing the trees, and then diffing the obtained text files to eventually compute a text-based diff.
 - _Constructing Variation Diffs Using Tree Diffing Algorithms_, Benjamin Moosherr, Bachelor's Thesis, 2023, [DOI 10.18725/OPARU-50108](https://dx.doi.org/10.18725/OPARU-50108): Benjamin added support for tree-differencing and integrated the GumTree differencer ([Github](https://github.com/GumTreeDiff/gumtree), [Paper](https://doi.org/10.1145/2642937.2642982)). In his thesis, Benjamin also reviewed a range of quality metrics for tree-diffs with focus on their applicability for rating variability-aware diffs. The [org.variantsync.diffdetective.experiments.thesis_bm](src/main/java/org/variantsync/diffdetective/experiments/thesis_bm) package implements the corresponding empirical study and may serve as an example on how to use the tree-differencing.
 - _Reverse Engineering Feature-Aware Commits From Software Product-Line Repositories_, Lukas Bormann, Bachelor's Thesis, 2023, [10.18725/OPARU-47892](https://dx.doi.org/10.18725/OPARU-47892): Lukas implemented an algorithm for feature-based commit-untangling, which turns variation diff into a series of smaller diffs, each of which contains an edit to a single feature or feature formula. This work was later refined in our publication _Views on Edits to Variational Software_ illustrated above.
-- _Inspecting the Evolution of Feature Annotations in Configurable Software_, Lukas Güthing, Master's Thesis, 2023: Lukas implemented different edge-types for associating variability annotations within variation diffs. He published his work later at VaMoS 2024 under the title _Explaining Edits to Variability Annotations in Evolving Software Product Lines_, illustrated above.
+- _Inspecting the Evolution of Feature Annotations in Configurable Software_, Lukas Güthing, Master's Thesis, 2023: Lukas implemented different edge-types for associating variability annotations within variation diffs. He published his work later at VaMoS 2024 under the title _Explaining Edits to Variability Annotations in Evolving Software Product Lines_, illustrated above. His work can be found in a [fork][forklg] of DiffDetective.
 - _Empirical Evaluation of Feature Trace Recording on the Edit History of Marlin_, Sören Viegener, Bachelor's Thesis, 2021, [DOI 10.18725/OPARU-38603](http://dx.doi.org/10.18725/OPARU-38603): In his thesis, Sören started the DiffDetective project and implemented the first version of an algorithm, which parses text-based diffs to C-preprocessor files to variation diffs. He also came up with an initial classification of edits, which we wanted to reuse to evaluate [Feature Trace Recording](https://variantsync.github.io/FeatureTraceRecording/), a method for deriving variability annotations from annotated patches.
 
 [documentation]: https://variantsync.github.io/DiffDetective/docs/javadoc

docs/teaser.png

@@ -742,10 +742,14 @@ public static DiffNode<DiffLinesLabel> fromID(int id, String label) {
      * Checks that the VariationDiff is in a valid state.
      * In particular, this method checks that all edges are well-formed (e.g., edges can be inconsistent because edges are double-linked).
      * This method also checks that a node with exactly one parent was edited, and that a node with exactly two parents was not edited.
+     * To check all children recursively, use {@link VariationDiff#assertConsistency}.
      * @see Assert#assertTrue
      * @throws AssertionError when an inconsistency is detected.
      */
     public void assertConsistency() {
+        // check that the projections are valid (i.e., node type specific consistency checks)
+        diffType.forAllTimesOfExistence(time -> this.projection(time).assertConsistency());
+
         // check consistency of children lists and edges
         for (final DiffNode<L> c : getAllChildren()) {
             Assert.assertTrue(isChild(c), () -> "Child " + c + " of " + this + " is neither a before nor an after child!");
@@ -769,6 +773,10 @@ public void assertConsistency() {
         if (pb != null && pa == null) {
             Assert.assertTrue(isRem());
         }
+        // the root was not edited
+        if (pb == null && pa == null) {
+            Assert.assertTrue(isNon());
+        }
         // a node with exactly two parents was not edited
         if (pb != null && pa != null) {
             Assert.assertTrue(isNon());
@@ -779,22 +787,6 @@ public void assertConsistency() {
                 Assert.assertTrue(pb.isNon());
             }
         }
-
-        // Else and Elif nodes have an If or Elif as parent.
-        if (this.isElse() || this.isElif()) {
-            Time.forAll(time -> {
-                if (getParent(time) != null) {
-                    Assert.assertTrue(getParent(time).isIf() || getParent(time).isElif(), time + " parent " + getParent(time) + " of " + this + " is neither IF nor ELIF!");
-                }
-            });
-        }
-
-        // Only if and elif nodes have a formula
-        if (this.isIf() || this.isElif()) {
-            Assert.assertTrue(this.getFormula() != null, "If or elif without feature mapping!");
-        } else {
-            Assert.assertTrue(this.getFormula() == null, "Node with type " + getNodeType() + " has a non null feature mapping");
-        }
     }
 
     /**

docs/variability-aware-differencing.png

@@ -130,4 +130,9 @@ public Node getFormula() {
     public int getID() {
         return getBackingNode().getID();
     }
+
+    @Override
+    public String toString() {
+        return String.format("Projection(%s, %s)", time, getBackingNode());
+    }
 };

src/main/java/org/variantsync/diffdetective/variation/diff/DiffNode.java

@@ -499,26 +499,28 @@ public VariationTreeNode<L> toVariationTree(final Map<? super T, VariationTreeNo
     }
 
     /**
-    * Checks that this node satisfies some easy to check invariants.
-    * In particular, this method checks that
-    * <ul>
-    * <li>if-chains are nested correctly,
-    * <li>the root is an {@link NodeType#IF} with the feature mapping {@code "true"},
-    * <li>the feature mapping is {@code null} iff {@code isConditionalAnnotation} is {@code false}
-    * and
-    * <li>all edges are well-formed (e.g., edges can be inconsistent because edges are
-    * double-linked).
-    * </ul>
-    *
-    * <p>Some invariants are not checked. These include
-    * <ul>
-    * <li>There should be no cycles and
-    * <li>{@link getID} should be unique in the whole variation tree.
-    * </ul>
-    *
-    * @see Assert#assertTrue
-    * @throws AssertionError when an inconsistency is detected.
-    */
+     * Checks that this node satisfies some easy to check invariants.
+     * In particular, this method checks that
+     * <ul>
+     * <li>if-chains are nested correctly,
+     * <li>the root is an {@link NodeType#IF} with the feature mapping {@code "true"},
+     * <li>the feature mapping is {@code null} iff {@code isConditionalAnnotation} is {@code false}
+     * and
+     * <li>all edges are well-formed (e.g., edges can be inconsistent because edges are
+     * double-linked).
+     * </ul>
+     *
+     * <p>Some invariants are not checked. These include
+     * <ul>
+     * <li>There should be no cycles,
+     * <li>{@link getID} should be unique in the whole variation tree, and
+     * <li>children are not checked recursively.
+     * </ul>
+     * Use {@link VariationTree#assertConsistency} to check all children recursively.
+     *
+     * @see Assert#assertTrue
+     * @throws AssertionError when an inconsistency is detected.
+     */
     public void assertConsistency() {
         // ELSE and ELIF nodes have an IF or ELIF as parent.
         if (isElse() || isElif()) {
@@ -549,6 +551,12 @@ public void assertConsistency() {
                 "The root has to have the feature mapping 'true'");
         }
 
+        // check that there is at most one ELIF/ELSE
+        Assert.assertTrue(
+            getChildren().stream().filter(c -> c.isElif() || c.isElse()).count() <= 1,
+            "There is more than one ELIF/ELSE node."
+        );
+
         // check consistency of children lists and edges
         for (var child : getChildren()) {
             Assert.assertTrue(

src/main/java/org/variantsync/diffdetective/variation/diff/Projection.java

@@ -5,6 +5,7 @@
 import org.variantsync.diffdetective.util.Assert;
 import org.variantsync.diffdetective.variation.DiffLinesLabel;
 import org.variantsync.diffdetective.variation.Label;
+import org.variantsync.diffdetective.variation.NodeType; // For Javadoc
 import org.variantsync.diffdetective.variation.diff.DiffNode;
 import org.variantsync.diffdetective.variation.diff.VariationDiff;
 import org.variantsync.diffdetective.variation.diff.Projection;
@@ -223,6 +224,17 @@ public String unparse() {
         return result.toString();
     }
 
+    /**
+     * Checks whether this {@link VariationTree} is consistent.
+     * Throws an error if this {@link VariationTree} is inconsistent (e.g., if there are multiple
+     * {@link NodeType#ELSE} nodes). Has no side-effects otherwise.
+     *
+     * @see VariationNode#assertConsistency
+     */
+    public void assertConsistency() {
+        forAllPreorder(VariationTreeNode::assertConsistency);
+    }
+
     @Override
     public String toString() {
         return "variation tree from " + source;