Merge branch 'main' into lissa

.github/workflows/deploy.yml

@@ -22,6 +22,7 @@ jobs:
     with:
       deploy: true
       with-submodules: true
+      runs-on: self-hosted
     secrets:
       OSSRH_USER: ${{secrets.OSSRH_USER}}
       OSSRH_TOKEN: ${{secrets.OSSRH_TOKEN}}

.github/workflows/docs.yml

@@ -14,10 +14,10 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3.5.2
+      - uses: actions/checkout@v4
         with:
           token: ${{ secrets.SDQ_TOKEN }}
-      - uses: actions/checkout@v3.5.2
+      - uses: actions/checkout@v4
         with:
           repository: ${{ github.repository }}.wiki
           path: wiki
@@ -31,6 +31,6 @@ jobs:
         run: cp -r ./docs/. ./wiki
 
       - name: Deploy 🚀
-        uses: stefanzweifel/git-auto-commit-action@v4
+        uses: stefanzweifel/git-auto-commit-action@v5
         with:
           repository: wiki

.github/workflows/format.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: true
           fetch-depth: 0
@@ -27,6 +27,6 @@ jobs:
       - name: Format with Spotless in Maven
         run: mvn -B spotless:apply --file pom.xml
       - name: Commit changes
-        uses: stefanzweifel/git-auto-commit-action@v4
+        uses: stefanzweifel/git-auto-commit-action@v5
         with:
           commit_message: Apply formatting changes

.github/workflows/maven-manual-release.yml

@@ -21,3 +21,4 @@ jobs:
     with:
       release-version: ${{ github.event.inputs.release-version }}
       next-version: ${{ github.event.inputs.next-version }}
+      runs-on: self-hosted

.github/workflows/maven-release.yml

@@ -9,6 +9,7 @@ jobs:
     uses: ardoco/actions/.github/workflows/maven-release.yml@main
     with:
       with-submodules: true
+      runs-on: self-hosted
     secrets:
       # Needs to be a personal access token to push as a certain user; otherwise actions won't be triggered.
       PAT: ${{ secrets.SDQ_TOKEN }}

README.md

@@ -6,7 +6,7 @@
 [![Latest Release](https://img.shields.io/github/release/ArDoCo/Core.svg)](https://github.com/ArDoCo/Core/releases/latest)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7274034.svg)](https://doi.org/10.5281/zenodo.7274034)
 
-The goal of this project is to connect architecture documentation and models while identifying missing or deviating
+The goal of this project is to connect architecture documentation and models with Traceability Link Recovery (TLR) while identifying missing or deviating
 elements (inconsistencies).
 An element can be any representable item of the model, like a component or a relation.
 To do so, we first create trace links and then make use of them and other information to identify inconsistencies.
@@ -17,11 +17,14 @@ of _[KASTEL - Institute of Information Security and Dependability](https://kaste
 the [KIT](https://www.kit.edu).
 
 ## User Interfaces
-To be able to execute the core algorithms from this repository, you can write own user interfaces that (should) use the [ArDoCoRunner](https://github.com/ArDoCo/Core/blob/main/pipeline/src/main/java/edu/kit/kastel/mcse/ardoco/core/pipeline/ArDoCoRunner.java).
 
-We provide an example Command Line Interface (CLI) at [ArDoCo/CLI](https://github.com/ArDoCo/CLI).
+To be able to execute the core algorithms from this repository, you can write own user interfaces that (should) use
+the [ArDoCoRunner](https://github.com/ArDoCo/Core/blob/main/pipeline/pipeline-core/src/main/java/edu/kit/kastel/mcse/ardoco/core/execution/runner/ArDoCoRunner.java).
 
-Future user interfaces like a Graphical User Interface (GUI) or a web interface are planned for the future.
+We provide an example Command Line Interface (CLI) at [ArDoCo/CLI](https://github.com/ArDoCo/CLI) as well as a simple Graphical User Interface (GUI)
+at [ArDoCo/GUI](https://github.com/ArDoCo/GUI).
+
+Future user interfaces like an enhanced GUI or a web interface are planned.
 
 ## Documentation
 
@@ -39,6 +42,7 @@ To test the Core, you could use case studies and benchmarks provided in ..
 ## Maven
 
 ```xml
+
 <dependencies>
 	<dependency>
 		<groupId>io.github.ardoco.core</groupId>
@@ -49,7 +53,9 @@ To test the Core, you could use case studies and benchmarks provided in ..
 ```
 
 For snapshot releases, make sure to add the following repository
+
 ```xml
+
 <repositories>
 	<repository>
 		<releases>
@@ -64,9 +70,31 @@ For snapshot releases, make sure to add the following repository
 </repositories>
 ```
 
+## Microservice for text preprocessing
+
+Text preprocessing works locally, but there is also the option to host a microservice for this.
+The benefit is that the models do not need to be loaded each time, saving some runtime (and local memory).
+
+The microservice can be found at [ArDoCo/StanfordCoreNLP-Provider-Service](https://github.com/ArDoCo/StanfordCoreNLP-Provider-Service/).
+
+The microservice is secured with credentials and the usage of the microservice needs to be activated and the URL of the microservice configured.
+These settings can be provided to the execution via environment variables.
+To do so, set the following variables:
+
+```env
+NLP_PROVIDER_SOURCE=microservice
+MICROSERVICE_URL=[microservice_url]
+SCNLP_SERVICE_USER=[your_username]
+SCNLP_SERVICE_PASSWORD=[your_password]
+```
+
+The first variable `NLP_PROVIDER_SOURCE=microservice` activates the microservice usage.
+The next three variables configure the connection, and you need to provide the configuration for your deployed microservice.
+
 ## Attribution
 
-The initial version of this project is based on the master thesis [Linking Software Architecture Documentation and Models](https://doi.org/10.5445/IR/1000126194).
+The initial version of this project is based on the master
+thesis [Linking Software Architecture Documentation and Models](https://doi.org/10.5445/IR/1000126194).
 
 ## Acknowledgements
 

framework/common/pom.xml

@@ -58,7 +58,7 @@
     <dependency>
       <groupId>org.xerial</groupId>
       <artifactId>sqlite-jdbc</artifactId>
-      <version>3.42.0.0</version>
+      <version>3.43.2.2</version>
     </dependency>
   </dependencies>
 </project>

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/api/models/tracelinks/InstanceLink.java

@@ -53,6 +53,16 @@ public InstanceLink(RecommendedInstance textualInstance, ModelInstance modelInst
         this.confidence.addAgentConfidence(claimant, probability);
     }
 
+    /**
+     * Add confidence to this link.
+     * 
+     * @param claimant   the claimant that wants to change the confidence
+     * @param confidence the confidence value to add
+     */
+    public final void addConfidence(Claimant claimant, double confidence) {
+        this.confidence.addAgentConfidence(claimant, confidence);
+    }
+
     /**
      * Returns the probability of the correctness of this link.
      *

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/api/text/POSTag.java

@@ -1,12 +1,16 @@
 /* Licensed under MIT 2021-2023. */
 package edu.kit.kastel.mcse.ardoco.core.api.text;
 
+import java.io.IOException;
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+
 /**
  * This class represents all valid part-of-speech (pos) tags
- *
  */
 public enum POSTag {
     //@formatter:off
@@ -77,4 +81,19 @@ public boolean isVerb() {
     public boolean isNoun() {
         return getTag().startsWith("NN");
     }
+
+    @JsonValue
+    public String toValue() {
+        return getTag();
+    }
+
+    @JsonCreator
+    public static POSTag forValue(String value) throws IOException {
+        try {
+            return get(value);
+        } catch (IllegalArgumentException e) {
+            throw new IOException("Cannot deserialize PosTag");
+        }
+    }
+
 }

framework/common/src/main/java/edu/kit/kastel/mcse/ardoco/core/api/text/Text.java

@@ -24,6 +24,14 @@ default int getLength() {
      */
     ImmutableList<Word> words();
 
+    /**
+     * Returns the word at the given index
+     *
+     * @param index the index
+     * @return the word at the given index
+     */
+    Word getWord(int index);
+
     /**
      * Returns the sentences of the text, ordered by appearance.
      *

framework/pom.xml

@@ -19,5 +19,6 @@
 
   <modules>
     <module>common</module>
+    <module>text-provider-json</module>
   </modules>
 </project>

framework/text-provider-json/README.md

@@ -0,0 +1,67 @@
+# JSON for text providers
+
+In this repository, we present a definition for transferring information about a preprocessed text via JSON.
+
+
+## JSON-Schema
+Below, you can find a simple presentation of the JSON-schema for the definition of a text for ArDoCo. Basically, a text consists of sentences and sentences consist of words along with the constituency tree. Words contain information about themselves and the relations (dependencies) to other words.
+
+The interfaces of ArDoCo require more, but the rest should be recoverable/calculateable from these entities with their data fields.
+
+An example JSON-file that validates against the schema can be found in [examples/example-text.json](./examples/example-text.json).
+
+### Text
+- sentences: [Sentence]
+
+### Sentence
+- sentenceNo: integer
+- constituencyTree: string
+- text: string
+- words: [Word]
+
+### Word
+- sentenceNo: integer
+- id: integer
+- text: string
+- lemma: string
+- posTag: posTag
+- outgoingDependencies: [{dependencyType, TargetWordId}]
+- incomingDependencies: [{dependencyType, TargetWordId}]
+
+### posTags
+```json
+enum: ["JJ", "JJR", "JJS", "RB", "RBR", "RBS", "WRB", "CC", "IN", "CD", "DT", "WDT", "EX", "FW", "LS", "NN", "NNS", "NNP", "NNPS", "PDT", "POS", "PRP", "PRP$", "WP$", "WP", "RP", "SYM", "TO", "UH", "VB", "VBD", "VBG", "VBN", "VBP", "VBZ", "MD", ".", ",", ":", "-LRB-", "-RRB-", "-NONE-", "``", "''", "$", "#"]
+```
+
+### dependencyTypes
+```json
+enum: ["APPOS", "NSUBJ", "POSS", "OBJ", "IOBJ", "NMOD", "NSUBJPASS", "POBJ", "AGENT", "NUM", "PREDET", "RCMOD", "CSUBJ", "CCOMP", "XCOMP", "OBL", "VOCATIVE", "EXPL", "DISLOCATED", "ADVCL", "ADVMOD", "DISCOURSE", "AUXILIARY", "COP", "MARK", "ACL", "AMOD", "DET", "CLF", "CASE", "CONJ", "CC", "FIXED", "FLAT", "COMPOUND", "LIST", "PARATAXIS", "ORPHAN", "GOES_WITH", "REPARANDUM", "PUNCT", "CSUBJ_PASS", "ACL_RELCL", "COMPOUND_PRT", "NMOD_POSS", "REF", "NSUBJ_XSUBJ", "NSUBJ_PASS_XSUBJ", "NSUBJ_RELSUBJ", "NSUBJ_PASS_RELSUBJ", "OBJ_RELOBJ"]
+```
+
+## Maven
+
+```xml
+<dependencies>
+	<dependency>
+		<groupId>io.github.ardoco.core</groupId>
+		<artifactId>text-provider-json</artifactId>
+		<version>YOUR_VERSION_HERE</version>
+	</dependency>
+</dependencies>
+```
+
+For snapshot releases, make sure to add the following repository
+```xml
+<repositories>
+	<repository>
+		<releases>
+			<enabled>false</enabled>
+		</releases>
+		<snapshots>
+			<enabled>true</enabled>
+		</snapshots>
+		<id>mavenSnapshot</id>
+		<url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
+	</repository>
+</repositories>
+```