Merge pull request #289 from fandango-fuzzer/286-add-comments-to-the-…

…contraintsystem 286 add comments to the contraintsystem
fandango-fuzzer · Jan 29, 2025 · 1a29d7e · 1a29d7e
2 parents b3ca178 + b152d16
commit 1a29d7e
Show file tree

Hide file tree

Showing 47 changed files with 526 additions and 27 deletions.
diff --git a/.github/workflows/python-tests.yml b/.github/workflows/python-tests.yml
@@ -48,13 +48,18 @@ jobs:
           pip install pygraphviz
 
       # Step 5: Install Python dependencies using make and run tests
-      - name: Install dependencies with Makefile and run tests
+      - name: Install dependencies with Makefile
         run: |
           python -m pip install --upgrade pip  # Upgrade pip to the latest version
           make install-test  # Install dependencies using the Makefile
           make tests  # Run the tests
 
-      # Step 6: Cache installed packages for system dependencies
+      # Step 6: Run tests using pytest
+      - name: Run tests with pytest
+        run: |
+          make tests  # Run the tests
+
+      # Step 7: Cache installed packages for system dependencies
       - name: Cache pygraphviz dependencies
         uses: actions/cache@v3
         with:

diff --git a/src/evaluation/__init__.py → evaluation/__init__.py b/src/evaluation/__init__.py → evaluation/__init__.py
diff --git a/src/evaluation/experiments/__init__.py → evaluation/experiments/__init__.py b/src/evaluation/experiments/__init__.py → evaluation/experiments/__init__.py
diff --git a/src/evaluation/experiments/faker/__init__.py → evaluation/experiments/faker/__init__.py b/src/evaluation/experiments/faker/__init__.py → evaluation/experiments/faker/__init__.py
diff --git a/src/evaluation/experiments/faker/faker.fan → evaluation/experiments/faker/faker.fan b/src/evaluation/experiments/faker/faker.fan → evaluation/experiments/faker/faker.fan
diff --git a/...ion/experiments/faker/faker_experiment.py → ...ion/experiments/faker/faker_experiment.py b/...ion/experiments/faker/faker_experiment.py → ...ion/experiments/faker/faker_experiment.py
diff --git a/src/evaluation/experiments/hash/__init__.py → evaluation/experiments/hash/__init__.py b/src/evaluation/experiments/hash/__init__.py → evaluation/experiments/hash/__init__.py
diff --git a/src/evaluation/experiments/hash/hash.fan → evaluation/experiments/hash/hash.fan b/src/evaluation/experiments/hash/hash.fan → evaluation/experiments/hash/hash.fan
diff --git a/...ation/experiments/hash/hash_experiment.py → ...ation/experiments/hash/hash_experiment.py b/...ation/experiments/hash/hash_experiment.py → ...ation/experiments/hash/hash_experiment.py
diff --git a/...evaluation/experiments/pixels/__init__.py → evaluation/experiments/pixels/__init__.py b/...evaluation/experiments/pixels/__init__.py → evaluation/experiments/pixels/__init__.py
diff --git a/src/evaluation/experiments/pixels/pixels.fan → evaluation/experiments/pixels/pixels.fan b/src/evaluation/experiments/pixels/pixels.fan → evaluation/experiments/pixels/pixels.fan
diff --git a/...n/experiments/pixels/pixels_experiment.py → ...n/experiments/pixels/pixels_experiment.py b/...n/experiments/pixels/pixels_experiment.py → ...n/experiments/pixels/pixels_experiment.py
diff --git a/...tion/experiments/transactions/__init__.py → ...tion/experiments/transactions/__init__.py b/...tion/experiments/transactions/__init__.py → ...tion/experiments/transactions/__init__.py
diff --git a/...experiments/transactions/transactions.fan → ...experiments/transactions/transactions.fan b/...experiments/transactions/transactions.fan → ...experiments/transactions/transactions.fan
diff --git a/.../experiments/transactions/transactions.py → .../experiments/transactions/transactions.py b/.../experiments/transactions/transactions.py → .../experiments/transactions/transactions.py
diff --git a/...valuation/experiments/voltage/__init__.py → evaluation/experiments/voltage/__init__.py b/...valuation/experiments/voltage/__init__.py → evaluation/experiments/voltage/__init__.py
diff --git a/...valuation/experiments/voltage/voltage.fan → evaluation/experiments/voltage/voltage.fan b/...valuation/experiments/voltage/voltage.fan → evaluation/experiments/voltage/voltage.fan
diff --git a/...experiments/voltage/voltage_experiment.py → ...experiments/voltage/voltage_experiment.py b/...experiments/voltage/voltage_experiment.py → ...experiments/voltage/voltage_experiment.py
diff --git a/...aluation/experiments/whitebox/__init__.py → evaluation/experiments/whitebox/__init__.py b/...aluation/experiments/whitebox/__init__.py → evaluation/experiments/whitebox/__init__.py
diff --git a/...evaluation/experiments/whitebox/bytes.fan → evaluation/experiments/whitebox/bytes.fan b/...evaluation/experiments/whitebox/bytes.fan → evaluation/experiments/whitebox/bytes.fan
diff --git a/...aluation/experiments/whitebox/whitebox.py → evaluation/experiments/whitebox/whitebox.py b/...aluation/experiments/whitebox/whitebox.py → evaluation/experiments/whitebox/whitebox.py
diff --git a/src/evaluation/experiments/whitebox/xml.fan → evaluation/experiments/whitebox/xml.fan b/src/evaluation/experiments/whitebox/xml.fan → evaluation/experiments/whitebox/xml.fan
diff --git a/src/evaluation/vs_isla/__init__.py → evaluation/vs_isla/__init__.py b/src/evaluation/vs_isla/__init__.py → evaluation/vs_isla/__init__.py
diff --git a/...uation/vs_isla/csv_evaluation/__init__.py → ...uation/vs_isla/csv_evaluation/__init__.py b/...uation/vs_isla/csv_evaluation/__init__.py → ...uation/vs_isla/csv_evaluation/__init__.py
diff --git a/...evaluation/vs_isla/csv_evaluation/csv.fan → evaluation/vs_isla/csv_evaluation/csv.fan b/...evaluation/vs_isla/csv_evaluation/csv.fan → evaluation/vs_isla/csv_evaluation/csv.fan
diff --git a/.../vs_isla/csv_evaluation/csv_evaluation.py → .../vs_isla/csv_evaluation/csv_evaluation.py b/.../vs_isla/csv_evaluation/csv_evaluation.py → .../vs_isla/csv_evaluation/csv_evaluation.py
diff --git a/..._isla/csv_evaluation/csv_isla_results.txt → ..._isla/csv_evaluation/csv_isla_results.txt b/..._isla/csv_evaluation/csv_isla_results.txt → ..._isla/csv_evaluation/csv_isla_results.txt
diff --git a/...ation/vs_isla/rest_evaluation/__init__.py → ...ation/vs_isla/rest_evaluation/__init__.py b/...ation/vs_isla/rest_evaluation/__init__.py → ...ation/vs_isla/rest_evaluation/__init__.py
diff --git a/...aluation/vs_isla/rest_evaluation/rest.fan → evaluation/vs_isla/rest_evaluation/rest.fan b/...aluation/vs_isla/rest_evaluation/rest.fan → evaluation/vs_isla/rest_evaluation/rest.fan
diff --git a/...s_isla/rest_evaluation/rest_evaluation.py → ...s_isla/rest_evaluation/rest_evaluation.py b/...s_isla/rest_evaluation/rest_evaluation.py → ...s_isla/rest_evaluation/rest_evaluation.py
diff --git a/...sla/rest_evaluation/rest_isla_results.txt → ...sla/rest_evaluation/rest_isla_results.txt b/...sla/rest_evaluation/rest_isla_results.txt → ...sla/rest_evaluation/rest_isla_results.txt
diff --git a/src/evaluation/vs_isla/run_evaluation.py → evaluation/vs_isla/run_evaluation.py b/src/evaluation/vs_isla/run_evaluation.py → evaluation/vs_isla/run_evaluation.py
diff --git a/...s_isla/scriptsizec_evaluation/__init__.py → ...s_isla/scriptsizec_evaluation/__init__.py b/...s_isla/scriptsizec_evaluation/__init__.py → ...s_isla/scriptsizec_evaluation/__init__.py
diff --git a/...la/scriptsizec_evaluation/scriptsizec.fan → ...la/scriptsizec_evaluation/scriptsizec.fan b/...la/scriptsizec_evaluation/scriptsizec.fan → ...la/scriptsizec_evaluation/scriptsizec.fan
diff --git a/...izec_evaluation/scriptsizec_evaluation.py → ...izec_evaluation/scriptsizec_evaluation.py b/...izec_evaluation/scriptsizec_evaluation.py → ...izec_evaluation/scriptsizec_evaluation.py
diff --git a/...c_evaluation/scriptsizec_isla_results.txt → ...c_evaluation/scriptsizec_isla_results.txt b/...c_evaluation/scriptsizec_isla_results.txt → ...c_evaluation/scriptsizec_isla_results.txt
diff --git a/...uation/vs_isla/tar_evaluation/__init__.py → ...uation/vs_isla/tar_evaluation/__init__.py b/...uation/vs_isla/tar_evaluation/__init__.py → ...uation/vs_isla/tar_evaluation/__init__.py
diff --git a/...evaluation/vs_isla/tar_evaluation/tar.fan → evaluation/vs_isla/tar_evaluation/tar.fan b/...evaluation/vs_isla/tar_evaluation/tar.fan → evaluation/vs_isla/tar_evaluation/tar.fan
diff --git a/.../vs_isla/tar_evaluation/tar_evaluation.py → .../vs_isla/tar_evaluation/tar_evaluation.py b/.../vs_isla/tar_evaluation/tar_evaluation.py → .../vs_isla/tar_evaluation/tar_evaluation.py
diff --git a/..._isla/tar_evaluation/tar_isla_results.txt → ..._isla/tar_evaluation/tar_isla_results.txt b/..._isla/tar_evaluation/tar_isla_results.txt → ..._isla/tar_evaluation/tar_isla_results.txt
diff --git a/...uation/vs_isla/xml_evaluation/__init__.py → ...uation/vs_isla/xml_evaluation/__init__.py b/...uation/vs_isla/xml_evaluation/__init__.py → ...uation/vs_isla/xml_evaluation/__init__.py
diff --git a/...evaluation/vs_isla/xml_evaluation/xml.fan → evaluation/vs_isla/xml_evaluation/xml.fan b/...evaluation/vs_isla/xml_evaluation/xml.fan → evaluation/vs_isla/xml_evaluation/xml.fan
diff --git a/.../vs_isla/xml_evaluation/xml_evaluation.py → .../vs_isla/xml_evaluation/xml_evaluation.py b/.../vs_isla/xml_evaluation/xml_evaluation.py → .../vs_isla/xml_evaluation/xml_evaluation.py
diff --git a/..._isla/xml_evaluation/xml_isla_results.txt → ..._isla/xml_evaluation/xml_isla_results.txt b/..._isla/xml_evaluation/xml_isla_results.txt → ..._isla/xml_evaluation/xml_isla_results.txt
diff --git a/src/fandango/constraints/base.py b/src/fandango/constraints/base.py
diff --git a/src/fandango/constraints/fitness.py b/src/fandango/constraints/fitness.py
@@ -1,3 +1,7 @@
+"""
+The `fitness` module provides the `Fitness` class and its subclasses `ValueFitness` and `ConstraintFitness`.
+"""
+
 import abc
 import enum
 import itertools
@@ -9,6 +13,10 @@
 
 
 class Comparison(enum.Enum):
+    """
+    Enum class for comparison operations.
+    """
+
     EQUAL = "=="
     NOT_EQUAL = "!="
     GREATER = ">"
@@ -18,17 +26,33 @@ class Comparison(enum.Enum):
 
 
 class ComparisonSide(enum.Enum):
+    """
+    Enum class for comparison side.
+    """
+
     LEFT = "left"
     RIGHT = "right"
 
 
 class FailingTree:
+    """
+    Class to represent a failing tree, i.e., a tree that does not satisfy a given constraint.
+    """
+
     def __init__(
         self,
         tree: DerivationTree,
         cause: "GeneticBase",
         suggestions: Optional[List[Tuple[Comparison, Any, ComparisonSide]]] = None,
     ):
+        """
+        Initialize the FailingTree with the given tree, cause, and suggestions.
+
+        :param DerivationTree tree: The tree that failed to satisfy the constraint.
+        :param GeneticBase cause: The cause of the failure.
+        :param Optional[List[Tuple[Comparison, Any, ComparisonSide]]] suggestions: The list of suggestions to
+        which causes the cause to fail.
+        """
         self.tree = tree
         self.cause = cause
         self.suggestions = suggestions or []
@@ -47,12 +71,26 @@ def __str__(self):
 
 
 class Fitness(abc.ABC):
+    """
+    Abstract class to represent the fitness of a tree.
+    """
+
     def __init__(self, success: bool, failing_trees: List[FailingTree] = None):
+        """
+        Initialize the Fitness with the given success and failing trees.
+
+        :param bool success: The success of the fitness.
+        :param Optional[List[FailingTree]] failing_trees: The list of failing trees.
+        """
         self.success = success
         self.failing_trees = failing_trees or []
 
     @abc.abstractmethod
     def fitness(self) -> float:
+        """
+        Abstract method to calculate the fitness of the tree.
+        :return float: The fitness of the tree.
+        """
         pass
 
     @abc.abstractmethod
@@ -61,13 +99,29 @@ def __copy__(self) -> "Fitness":
 
 
 class ValueFitness(Fitness):
+    """
+    Class to represent the fitness of a tree based on calculated values.
+    The fitness is calculated as the average of the values.
+    This class contrast the `ConstraintFitness` class, which calculates the fitness based on the number of
+    constraints satisfied.
+    """
+
     def __init__(
         self, values: List[float] = None, failing_trees: List[FailingTree] = None
     ):
+        """
+        Initialize the ValueFitness with the given values and failing trees.
+        :param Optional[List[float]] values: The list of values.
+        :param Optional[List[FailingTree]] failing_trees: The list of failing trees.
+        """
         super().__init__(True, failing_trees)
         self.values = values or []
 
     def fitness(self) -> float:
+        """
+        Calculate the fitness of the tree as the average of the values.
+        :return float: The fitness of the tree.
+        """
         if self.values:
             return sum(self.values) / len(self.values)
         else:
@@ -78,18 +132,36 @@ def __copy__(self) -> Fitness:
 
 
 class ConstraintFitness(Fitness):
+    """
+    Class to represent the fitness of a tree based on constraints.
+    The fitness is calculated as the number of constraints solved by the tree divided by the total number of
+    constraints.
+    """
+
     def __init__(
         self,
         solved: int,
         total: int,
         success: bool,
         failing_trees: List[FailingTree] = None,
     ):
+        """
+        Initialize the ConstraintFitness with the given solved, total, success, and failing trees.
+        :param int solved: The number of constraints solved by the tree.
+        :param int total: The total number of constraints.
+        :param bool success: The success of the fitness.
+        :param Optional[List[FailingTree]] failing_trees: The list of failing trees.
+        """
         super().__init__(success, failing_trees)
         self.solved = solved
         self.total = total
 
     def fitness(self) -> float:
+        """
+        Calculate the fitness of the tree as the number of constraints solved by the tree divided by the total number of
+        constraints.
+        :return float: The fitness of the tree.
+        """
         if self.total:
             return self.solved / self.total
         else:
@@ -105,17 +177,31 @@ def __copy__(self) -> Fitness:
 
 
 class GeneticBase(abc.ABC):
+    """
+    Abstract class to represent a genetic base.
+    """
+
     def __init__(
         self,
         searches: Optional[Dict[str, NonTerminalSearch]] = None,
         local_variables: Optional[Dict[str, Any]] = None,
         global_variables: Optional[Dict[str, Any]] = None,
     ):
+        """
+        Initialize the GeneticBase with the given searches, local variables, and global variables.
+        :param Optional[Dict[str, NonTerminalSearch]] searches: The dictionary of searches.
+        :param Optional[Dict[str, Any]] local_variables: The dictionary of local variables.
+        :param Optional[Dict[str, Any]] global_variables: The dictionary of global variables.
+        """
         self.searches = searches or dict()
         self.local_variables = local_variables or dict()
         self.global_variables = global_variables or dict()
 
     def get_access_points(self):
+        """
+        Get the access points of the genetic base, i.e., the non-terminal that are considered in this genetic base.
+        :return List[NonTerminal]: The list of access points.
+        """
         return sum(
             [search.get_access_points() for search in self.searches.values()], []
         )
@@ -126,6 +212,12 @@ def fitness(
         tree: DerivationTree,
         scope: Optional[Dict[NonTerminal, DerivationTree]] = None,
     ) -> Fitness:
+        """
+        Abstract method to calculate the fitness of the tree.
+        :param DerivationTree tree: The tree to calculate the fitness.
+        :param Optional[Dict[NonTerminal, DerivationTree]] scope: The scope of non-terminals matching to trees.
+        :return Fitness: The fitness of the tree.
+        """
         raise NotImplementedError("Fitness function not implemented")
 
     @staticmethod
@@ -140,6 +232,13 @@ def combinations(
         tree: DerivationTree,
         scope: Optional[Dict[NonTerminal, DerivationTree]] = None,
     ):
+        """
+        Get all possible combinations of trees that satisfy the searches.
+        :param DerivationTree tree: The tree to calculate the fitness.
+        :param Optional[Dict[NonTerminal, DerivationTree]] scope: The scope of non-terminals matching to trees.
+        :return List[List[Tuple[str, DerivationTree]]]: The list of combinations of trees that fill all non-terminals
+        in the genetic base.
+        """
         nodes: List[List[Tuple[str, DerivationTree]]] = []
         for name, search in self.searches.items():
             nodes.append(
@@ -151,10 +250,21 @@ def check(
         self,
         tree: DerivationTree,
         scope: Optional[Dict[NonTerminal, DerivationTree]] = None,
-    ):
+    ) -> bool:
+        """
+        Check if the tree satisfies the genetic base.
+        :param DerivationTree tree: The tree to check.
+        :param Optional[Dict[NonTerminal, DerivationTree]] scope: The scope of non-terminals matching to trees.
+        :return bool: True if the tree satisfies the genetic base, False otherwise.
+        """
         return self.fitness(tree, scope).success
 
     def get_failing_nodes(self, tree: DerivationTree):
+        """
+        Get the failing nodes of the tree.
+        :param DerivationTree tree: The tree to check.
+        :return List[FailingTree]: The list of failing trees
+        """
         return self.fitness(tree).failing_trees
 
     @abc.abstractmethod