Merge branch 'feature/coding-conventions' into feature/android_action

.github/workflows/build_and_test.yml

@@ -14,9 +14,6 @@ jobs:
   build-and-test-analysis:
     runs-on: ubuntu-latest
 
-    # Do not run this build in the merge queue
-    if: github.event_name != 'merge_group'
-
     steps:
       - name: Checkout source code
         uses: actions/checkout@v4
@@ -35,6 +32,8 @@ jobs:
           key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
           restore-keys: |
             ${{ runner.os }}-maven-
+      - name: Event name
+        run: echo ${{ github.event_name }}
       - name: Run maven command
         run: mvn clean verify -DrunAnalysisTests
 
@@ -75,9 +74,6 @@ jobs:
   build-and-test-scanner-soot:
     runs-on: ubuntu-latest
 
-    # Do not run this build in the merge queue
-    if: github.event_name != 'merge_group'
-
     steps:
       - name: Checkout source code
         uses: actions/checkout@v4

.github/workflows/style.yml

@@ -0,0 +1,23 @@
+name: Style checker
+description: Check the formatting. Use "mvn spotless:apply" to format the code.
+
+on:
+  push:
+
+jobs:
+  check-formatting:
+    runs-on: ubuntu-latest
+    name: Check the style
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v4
+      # Restores Maven dependecies
+      - name: Restore local Maven repository
+        uses: actions/cache@v4
+        with:
+          path: ~/.m2/repository
+          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+          restore-keys: |
+            ${{ runner.os }}-maven-
+      - name: Run spotless checks
+        run: mvn spotless:check

CODING.md

@@ -0,0 +1,11 @@
+# Coding Guidelines
+
+We aim for keeping the code as clean as possible. To do so, we follow the Google style guide for Java. You can check whether your code complies with the guidelines, simply run the command
+```mvn spotless:check```
+
+You do not need to install a plugin to format your code. The command
+
+```mvn spotless:apply```
+
+formats all files. Note that the code will also be formatted when building the project, e.g. by
+```mvn clean package -DskipTests```

CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contribution to CryptoAnaylsis
+You can contribute with issues and PRs. Simply filing issues for problems you encounter is a great 
+way to contribute. Contributing implementations is greatly appreciated.
+
+## DOs and DON'Ts
+Please do:
+- **DO** follow the [coding guidelines](CODING.md)
+- **DO** follow the naming conventions for branches.
+- **DO** include tests when adding new features. When fixing bugs, start with adding a test that highlights how the current behavior is broken.
+- **DO** keep the discussions focused. When a new or related topic comes up it's often better to create new issue than to side track the discussion.
+- **DO** document your changes in detail in the pull requests.
+
+Please do not:
+- **DON'T** make PRs for coding guidelines changes.
+- **DON'T** create a big pull requests with no related issue. Instead, first file an issue.
+- **DON'T** submit PRs that use licensed files we are not allowed to use.
+- **DON'T** add or change API related code without filing an issue and discussing it with the project leads first
+
+## Suggested Workflow
+
+We aim for the following workflow:
+
+1. Create an issue for your work.
+  - You can skip this step for trivial changes.
+  - Reuse an existing issue on the topic, if there is one.
+  - If you want to implement the issue yourself, please state this. 
+2. Create a personal fork of the repository on GitHub. 
+3. In your fork, create a new branch of develop (`git checkout -b mybranch`).
+    - Apply branch naming rules (see below)
+3. Make and commit your changes to your branch.
+    - Keep changes as small as possible.
+4. Add new tests corresponding to your change, if applicable.
+  - Minor changes, like fixing typos, adding documentation or non-critical bugfixes may are excluded.
+5. Build the repository with your changes (e.g. by `mvn clean package -DrunAllTests`).
+    - Make sure that the builds are clean.
+    - Make sure that the tests are all passing, including your new tests.
+6. Create a pull request against this repository's `develop` branch.
+    - If the branch is not yet ready, give the PR's name a `WIP` prefix. 
+    - Check if all the Continuous Integration checks are passing.
+7. When you are done, add one or more reviewer.
+    - Make sure the PR has the latest changes from `develop` merged in it.
+8. Wait for feedback or approval of your changes.
+9. When remaining issues from feedback are resolved and all checks are green, your PR will be merged by one of the reviewers.
+    - Delete the source branch with the merge.
+
+
+## Branches
+
+This repository contains two central branches. The **master** and the **develop** branch. The develop branch is default. Both branches are *protected* against direct write access, thus Pull Requests are necessary to push into them. Other branches are unprotected and can be created and deleted by a contributer
+
+The `master` branch holds the lastest stable release of the application.
+
+The `develop` branch holds the lastest development version of the application.
+
+New branches should *always* target the `develop`. Once, we decide to release a new version, we merge the changes from
+the `develop` branch into the `master` branch and deploy the changes to Maven Central.
+
+### Branching
+Since `master` and `develop` branches are protected, working with branches is mandatory. 
+
+In general each branch shall only be responsible for one idea. 
+This way we try to minimize the amount of changes in all branches, which makes it easier to review.
+
+### Naming Branches
+Branch names should be declarative, meaning the name of a branch shall always yield what it's ultimately going to change. Since a branch can target different aspects of development (e.g. feature, bug-fix, refactoring, etc.) their names shall have that information also included by adding a PREFIX. The scheme of a branch name look as follows: `PREFIX/tell-what-it-does`
+
+We suggest the following prefixes:
+```
+feature/    // For new features
+fix/        // Fixes a bug
+```
+
+### Tests
+Since we have multiple modules, we configured Maven to run subsets of the tests. You have the following options:
+
+- Use `-DrunAnalysis` to run the tests for the analysis (CryptoAnalysis)
+- Use `-DrunSootTests` to run the tests for the HeadlessJavaScanner with Soot enabled
+- Use `-DrunSootUpTests` to run the tests for the HeadlessJavaScanner with SootUp enabled (not implemented yet)
+- Use `-DrunOpalTests` to run the tests for the HeadlessJavaScanner with Opal enabled (not implemented yet)
+- Use `-DrunAndroidTests` to run the tests for the HeadlessAndroidScanner
+- Use `-DrunAllTests` to run the tests for CryptoAnalysis, HeadlessAndroidScanner and HeadlessJavaScanner (with Soot)
+
+In all cases, the project is built and the corresponding tests are executed. For example, `mvn clean package -DrunAnalysisTests` builds the project and runs only the tests for the `CryptoAnalysis` module. You can also apply multiple arguments, e.g. `mvn clean package -DrunAnalysisTests -DrunSootTests` runs the tests for the CryptoAnalysis and HeadlessJavaScanner (with Soot) modules.
+
+---
+*Based on the .NET Runtime contributing guidelines*

CryptoAnalysis/src/main/java/crypto/analysis/AlternativeReqPredicate.java

@@ -3,90 +3,91 @@
 import boomerang.scene.Statement;
 import crypto.rules.CrySLPredicate;
 import crypto.rules.ISLConstraint;
-
 import java.util.ArrayList;
 import java.util.List;
 import java.util.stream.Collectors;
 
 public class AlternativeReqPredicate implements ISLConstraint {
 
-	private final List<CrySLPredicate> alternatives;
-	private final Statement stmt;
-	private final int paramIndex;
+    private final List<CrySLPredicate> alternatives;
+    private final Statement stmt;
+    private final int paramIndex;
 
-	public AlternativeReqPredicate(CrySLPredicate alternativeOne, Statement stmt, int paramIndex) {
-		this.alternatives = new ArrayList<>();
-		this.alternatives.add(alternativeOne);
-		this.stmt = stmt;
-		this.paramIndex = paramIndex;
-	}
+    public AlternativeReqPredicate(CrySLPredicate alternativeOne, Statement stmt, int paramIndex) {
+        this.alternatives = new ArrayList<>();
+        this.alternatives.add(alternativeOne);
+        this.stmt = stmt;
+        this.paramIndex = paramIndex;
+    }
 
-	@Override
-	public int hashCode() {
-		final int prime = 31;
-		int result = 1;
-		result = prime * result + ((alternatives == null) ? 0 : alternatives.hashCode());
-		result = prime * result + ((stmt == null) ? 0 : stmt.hashCode());
-		result = prime * result + paramIndex;
-		return result;
-	}
+    @Override
+    public int hashCode() {
+        final int prime = 31;
+        int result = 1;
+        result = prime * result + ((alternatives == null) ? 0 : alternatives.hashCode());
+        result = prime * result + ((stmt == null) ? 0 : stmt.hashCode());
+        result = prime * result + paramIndex;
+        return result;
+    }
 
-	@Override
-	public boolean equals(Object obj) {
-		if (this == obj)
-			return true;
-		if (obj == null)
-			return false;
-		if (getClass() != obj.getClass())
-			return false;
-		AlternativeReqPredicate other = (AlternativeReqPredicate) obj;
-		if (alternatives == null) {
-			if (other.alternatives != null)
-				return false;
-		} else if (!alternatives.equals(other.alternatives))
-			return false;
-		if (stmt == null) {
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) return true;
+        if (obj == null) return false;
+        if (getClass() != obj.getClass()) return false;
+        AlternativeReqPredicate other = (AlternativeReqPredicate) obj;
+        if (alternatives == null) {
+            if (other.alternatives != null) return false;
+        } else if (!alternatives.equals(other.alternatives)) return false;
+        if (stmt == null) {
             return other.stmt == null;
-		} else if (!stmt.equals(other.stmt)) {
-			return false;
-		}
+        } else if (!stmt.equals(other.stmt)) {
+            return false;
+        }
 
-		return paramIndex == other.paramIndex;
+        return paramIndex == other.paramIndex;
     }
 
-	public Statement getLocation() {
-		return stmt;
-	}
+    public Statement getLocation() {
+        return stmt;
+    }
 
-	public int getParamIndex() {
-		return paramIndex;
-	}
+    public int getParamIndex() {
+        return paramIndex;
+    }
 
-	@Override
-	public String toString() {
-		return alternatives.stream().map(CrySLPredicate::toString).collect(Collectors.joining(" OR ")) + " @ " + stmt + " @ index " + paramIndex;
-	}
+    @Override
+    public String toString() {
+        return alternatives.stream()
+                        .map(CrySLPredicate::toString)
+                        .collect(Collectors.joining(" OR "))
+                + " @ "
+                + stmt
+                + " @ index "
+                + paramIndex;
+    }
 
-	@Override
-	public String getName() {
-		return alternatives.stream().map(CrySLPredicate::getName).collect(Collectors.joining(" OR "));
-	}
+    @Override
+    public String getName() {
+        return alternatives.stream()
+                .map(CrySLPredicate::getName)
+                .collect(Collectors.joining(" OR "));
+    }
 
-	@Override
-	public List<String> getInvolvedVarNames() {
-		List<String> involvedVarNames = new ArrayList<>();
-		for (CrySLPredicate alt : alternatives) {
-			involvedVarNames.addAll(alt.getInvolvedVarNames());
-		}
-		return involvedVarNames;
-	}
+    @Override
+    public List<String> getInvolvedVarNames() {
+        List<String> involvedVarNames = new ArrayList<>();
+        for (CrySLPredicate alt : alternatives) {
+            involvedVarNames.addAll(alt.getInvolvedVarNames());
+        }
+        return involvedVarNames;
+    }
 
     public List<CrySLPredicate> getAlternatives() {
-		return alternatives;
-	}
-
-	public void addAlternative(CrySLPredicate newAlt) {
-		alternatives.add(newAlt);
-	}
+        return alternatives;
+    }
 
+    public void addAlternative(CrySLPredicate newAlt) {
+        alternatives.add(newAlt);
+    }
 }

CryptoAnalysis/src/main/java/crypto/analysis/AnalysisSeedWithEnsuredPredicate.java

@@ -8,15 +8,18 @@
 import com.google.common.collect.HashMultimap;
 import com.google.common.collect.Multimap;
 import crypto.rules.CrySLPredicate;
-import typestate.TransitionFunction;
-
 import java.util.Collection;
+import typestate.TransitionFunction;
 
 public class AnalysisSeedWithEnsuredPredicate extends IAnalysisSeed {
 
     private final Multimap<Statement, Integer> relevantStatements;
 
-    public AnalysisSeedWithEnsuredPredicate(CryptoScanner scanner, Statement statement, Val fact, ForwardBoomerangResults<TransitionFunction> results) {
+    public AnalysisSeedWithEnsuredPredicate(
+            CryptoScanner scanner,
+            Statement statement,
+            Val fact,
+            ForwardBoomerangResults<TransitionFunction> results) {
         super(scanner, statement, fact, results);
 
         relevantStatements = HashMultimap.create();
@@ -50,15 +53,17 @@ public void execute() {
     }
 
     @Override
-    public void expectPredicate(Statement statement, CrySLPredicate predicate, IAnalysisSeed seed, int paramIndex) {
+    public void expectPredicate(
+            Statement statement, CrySLPredicate predicate, IAnalysisSeed seed, int paramIndex) {
         CrySLPredicate predToBeEnsured;
         if (predicate.isNegated()) {
             predToBeEnsured = predicate.invertNegation();
         } else {
             predToBeEnsured = predicate;
         }
 
-        expectedPredicates.put(statement, new ExpectedPredicateOnSeed(predToBeEnsured, seed, paramIndex));
+        expectedPredicates.put(
+                statement, new ExpectedPredicateOnSeed(predToBeEnsured, seed, paramIndex));
 
         for (Statement relStatement : relevantStatements.keySet()) {
             if (!relStatement.containsInvokeExpr()) {
@@ -81,7 +86,8 @@ public void expectPredicate(Statement statement, CrySLPredicate predicate, IAnal
                 }
 
                 // TODO from statement
-                Collection<Val> values = otherSeed.getAnalysisResults().asStatementValWeightTable().columnKeySet();
+                Collection<Val> values =
+                        otherSeed.getAnalysisResults().asStatementValWeightTable().columnKeySet();
                 if (values.contains(base)) {
                     for (Integer index : relevantStatements.get(relStatement)) {
 
@@ -100,7 +106,8 @@ public void expectPredicate(Statement statement, CrySLPredicate predicate, IAnal
 
     public void addEnsuredPredicate(EnsuredCrySLPredicate predicate) {
         for (Statement statement : expectedPredicates.keySet()) {
-            Collection<ExpectedPredicateOnSeed> predicateOnSeeds = expectedPredicates.get(statement);
+            Collection<ExpectedPredicateOnSeed> predicateOnSeeds =
+                    expectedPredicates.get(statement);
 
             for (ExpectedPredicateOnSeed predOnSeed : predicateOnSeeds) {
                 if (!predOnSeed.getPredicate().equals(predicate.getPredicate())) {
@@ -111,7 +118,8 @@ public void addEnsuredPredicate(EnsuredCrySLPredicate predicate) {
                     continue;
                 }
 
-                AnalysisSeedWithSpecification seedWithSpec = (AnalysisSeedWithSpecification) predOnSeed.getSeed();
+                AnalysisSeedWithSpecification seedWithSpec =
+                        (AnalysisSeedWithSpecification) predOnSeed.getSeed();
                 seedWithSpec.addEnsuredPredicate(predicate, statement, predOnSeed.getParamIndex());
             }
         }
@@ -135,5 +143,4 @@ public boolean equals(Object obj) {
     public String toString() {
         return "AnalysisSeedWithoutSpec [" + super.toString() + "]";
     }
-
 }