Refactor to use the Spoon library

.dockerignore

@@ -1,13 +1,17 @@
 .appends
 .git
 .github
-.gitignore
-.gitattributes
+.gradle
+.idea
+build
+gradle
+tests
 .dockerignore
+.gitattributes
+.gitignore
 Dockerfile
-bin/generate-test-data.sh
 bin/run-in-docker.sh
-bin/run-tests-in-docker.sh
 bin/run-tests.sh
-src/test/
-tests/
+bin/run-tests-in-docker.sh
+gradlew
+gradlew.bat

.gitattributes

@@ -0,0 +1 @@
+*.approved.* binary

.github/workflows/test.yml

@@ -22,6 +22,8 @@ jobs:
           distribution: "temurin"
       - name: Test with Gradle
         run: ./gradlew --no-daemon --continue test
+      - name: Upload test coverage
+        uses: coverallsapp/github-action@3dfc5567390f6fa9267c0ee9c251e4c8c3f18949
       - name: Create test summary
         uses: test-summary/action@fee35d7df20790255fe6aa92cf0f6d28092ecf2f
         with:

.gitignore

@@ -2,6 +2,7 @@
 .settings/
 .project
 .classpath
+src/test/resources/**/*.received.txt
 tests/**/*/representation.txt
 tests/**/*/representation.json
 tests/**/*/mapping.json

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Thank you so much for contributing! 🎉
+
+We welcome contributions of all sorts and sizes, from reporting issues to submitting patches, as well as joining discussions on the [Java forum][java-forum].
+
+Unprompted (without an issue) PRs with small bugfixes are welcome.
+However, if you want to propose bigger changes, make sure to post on the [forum][java-forum] first so that we can discuss it.
+
+## Code of Conduct
+
+Help us keep Exercism welcoming.
+Please read and abide by the [Code of Conduct][coc].
+
+## Contributing to Exercism
+
+If you are new to contributing to Exercism, please read:
+
+- [Being a good community member][community-docs]
+- [Contributing via GitHub][contributing-docs-github]
+
+## How does this project work?
+
+Start by reading up on Exercism Representers:
+
+- [Exercism Representers introduction][representer-docs-intro]
+- [The Representer interface][representer-docs-interface]
+- [Normalization within Representers][representer-docs-normalization]
+
+[coc]: https://github.com/exercism/java-analyzer/blob/main/CODE_OF_CONDUCT.md
+[java-forum]: https://forum.exercism.org/c/programming/java/91
+[community-docs]: https://exercism.org/docs/community/being-a-good-community-member
+[contributing-docs-github]: https://exercism.org/docs/building/github
+[representer-docs-interface]: https://exercism.org/docs/building/tooling/representers/interface
+[representer-docs-intro]: https://exercism.org/docs/building/tooling/representers
+[representer-docs-normalization]: https://exercism.org/docs/building/tooling/representers/normalization

Dockerfile

@@ -2,11 +2,12 @@ FROM gradle:8.5-jdk21 AS build
 
 WORKDIR /app
 COPY . /app
-
-RUN gradle -i --stacktrace clean build shadowJar
+RUN gradle -i --stacktrace clean build
 
 FROM eclipse-temurin:21
 
+ENV LOGGING_LEVEL=INFO
+
 WORKDIR /opt/representer
 COPY ./bin/run.sh bin/run.sh
 COPY --from=build /app/build/libs/java-representer.jar .

README.md

@@ -1,17 +1,75 @@
-# Exercism java-representer
+# Java Representer [![Coverage Status][coveralls-badge]][coveralls-report]
 
-Java representer takes a Java exercise solution and provides a normalized representation of it.
-The representer implements the [representer interface](https://exercism.org/docs/building/tooling/representers)
+This repository contains the source code for the [Representer][representer-docs] used by the Java track on Exercism.
+It takes a Java exercise solution submitted by a student and transforms it into a normalized representation.
 
+## Contributing
 
-## Quickstart
+If you want to contribute to the Java Representer, please refer to the [Contributing Guide][contributing-guide].
 
-### Docker
+## Usage
 
-1. Create image
+### Running directly
 
-`sudo docker build --no-cache -t exercism/java-representer .`
+Start by building the JAR using Gradle:
 
-2. Run the container
+```sh
+./gradlew build
+```
 
-`sudo docker run  -v <EXERCISES_FOLDER>:/app/data exercism/java-representer <EXERCISE_SLUG> /app/data/`
+Then, run the Java Representer using `build/libs/java-representer.jar`.
+For example, to create a representation for a solution to the `leap` exercise, run:
+
+```sh
+java -jar build/libs/java-representer.jar leap /path/to/leap /path/to/output/folder
+```
+
+The Representer output can be found in the following files inside the `/path/to/output/folder` directory:
+
+- `representation.txt` - Contains the normalized representation of the Java code inside the solution.
+- `mapping.json` - Contains a mapping between the generated placeholders used in the representation and the original identifiers.
+- `representation.json` - Contains metadata.
+
+### Running with Docker
+
+To run the Java Representer using Docker, first build and tag the Docker image:
+
+```sh
+docker build -t exercism/java-representer .
+```
+
+Then, run the image and mount the directory of the solution to represent.
+For example, to create a representation for a solution to the `leap` exercise, run:
+
+```sh
+docker run -v /path/to/leap:/input -v /path/to/output/folder:/output exercism/java-representer leap /input /output
+```
+
+The Representer output can be found in the following files inside the `/path/to/output/folder` directory:
+
+- `representation.txt` - Contains the normalized representation of the Java code inside the solution.
+- `mapping.json` - Contains a mapping between the generated placeholders used in the representation and the original identifiers.
+- `representation.json` - Contains metadata.
+
+## Tests
+
+### Unit tests
+
+To run the unit tests:
+
+```sh
+./gradlew test
+```
+
+### Smoke tests
+
+To run the smoke tests using Docker:
+
+```sh
+bin/run-tests-in-docker.sh
+```
+
+[contributing-guide]: https://github.com/exercism/java-representer/blob/main/CONTRIBUTING.md
+[representer-docs]: https://exercism.org/docs/building/tooling/representers
+[coveralls-badge]: https://coveralls.io/repos/github/exercism/java-representer/badge.svg?branch=main
+[coveralls-report]: https://coveralls.io/github/exercism/java-representer?branch=main

bin/run-in-docker.sh

@@ -14,11 +14,11 @@
 # The test results are formatted according to the specifications at https://github.com/exercism/docs/blob/main/building/tooling/representers/interface.md
 
 # Example:
-# ./bin/run-in-docker.sh two-fer /absolute/path/to/two-fer/solution/folder/ /absolute/path/to/output/directory/
+# ./bin/run-in-docker.sh two-fer /absolute/path/to/two-fer/solution/folder /absolute/path/to/output/directory
 
 # If any required arguments is missing, print the usage and exit
 if [ -z "$1" ] || [ -z "$2" ] || [ -z "$3" ]; then
-    echo "usage: ./bin/run-in-docker.sh exercise-slug /absolute/path/to/solution/folder/ /absolute/path/to/output/directory/"
+    echo "usage: ./bin/run-in-docker.sh exercise-slug /absolute/path/to/solution/folder /absolute/path/to/output/directory"
     exit 1
 fi
 
@@ -40,4 +40,4 @@ docker run \
     --mount type=bind,source="${input_dir}",destination=/solution \
     --mount type=bind,source="${output_dir}",destination=/output \
     --mount type=tmpfs,destination=/tmp \
-    exercism/java-representer "${slug}" /solution /output 
+    exercism/java-representer "${slug}" /solution /output

bin/run-tests.sh

@@ -18,7 +18,7 @@ for test_dir in tests/*; do
     test_dir_name=$(basename "${test_dir}")
     test_dir_path=$(realpath "${test_dir}")
 
-    bin/run.sh "${test_dir_name}" "${test_dir_path}/" "${test_dir_path}/"
+    bin/run.sh "${test_dir_name}" "${test_dir_path}" "${test_dir_path}"
 
     for file in representation.txt representation.json mapping.json; do
         expected_file="expected_${file}"

bin/run.sh

@@ -1,3 +1,3 @@
 #!/bin/sh
 
-java -jar /opt/representer/java-representer.jar $1 $2
+java -jar /opt/representer/java-representer.jar "$@"

build.gradle

@@ -1,7 +1,8 @@
 plugins {
-    id "com.github.johnrengelman.shadow" version "8.1.1"
     id "java"
     id "application"
+    id "jacoco"
+    id "com.github.johnrengelman.shadow" version "8.1.1"
 }
 
 group = "org.exercism"
@@ -13,14 +14,16 @@ repositories {
 }
 
 dependencies {
-    implementation "org.json:json:20231013"
-    implementation "com.github.javaparser:javaparser-symbol-solver-core:3.25.7"
-    implementation "org.apache.logging.log4j:log4j-api:2.22.1"
-    implementation "org.apache.logging.log4j:log4j-core:2.22.1"
-
-    testImplementation "junit:junit:4.13.2"
-    testImplementation "org.assertj:assertj-core:3.25.0"
-    testImplementation "org.hamcrest:hamcrest-all:1.3"
+    implementation "fr.inria.gforge.spoon:spoon-core:10.4.2"
+    implementation "com.google.code.gson:gson:2.10.1"
+    implementation "org.slf4j:slf4j-api:2.0.10"
+    implementation "ch.qos.logback:logback-core:1.4.12"
+    implementation "ch.qos.logback:logback-classic:1.4.12"
+
+    testImplementation platform("org.junit:junit-bom:5.10.0")
+    testImplementation "org.junit.jupiter:junit-jupiter"
+    testImplementation "org.assertj:assertj-core:3.25.1"
+    testImplementation "com.approvaltests:approvaltests:22.3.2"
 }
 
 shadowJar {
@@ -33,9 +36,20 @@ artifacts {
 }
 
 test {
+    useJUnitPlatform()
+
     testLogging {
         exceptionFormat = "full"
         showStandardStreams = true
         events = ["passed", "failed", "skipped"]
     }
+
+    finalizedBy jacocoTestReport
+}
+
+jacocoTestReport {
+    dependsOn test
+    reports {
+        xml.required = true
+    }
 }

src/main/java/representer/OutputWriter.java

@@ -0,0 +1,55 @@
+package representer;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonObject;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.FileWriter;
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.Map;
+import java.util.TreeMap;
+
+class OutputWriter {
+    private static final int REPRESENTER_VERSION = 2;
+    private static final Gson GSON = new GsonBuilder().setPrettyPrinting().create();
+    private static final Logger LOGGER = LoggerFactory.getLogger(OutputWriter.class);
+
+    private final Path outputPath;
+
+    OutputWriter(Path outputPath) {
+        this.outputPath = outputPath;
+    }
+
+    void write(Representation representation) throws IOException {
+        writeRepresentation(representation.representation(), this.outputPath.resolve("representation.txt"));
+        writePlaceholders(representation.placeholders(), this.outputPath.resolve("mapping.json"));
+        writeMetadata(this.outputPath.resolve("representation.json"));
+    }
+
+    private void writeRepresentation(String representation, Path path) throws IOException {
+        LOGGER.info("Writing representation to {}", path);
+        try (var writer = new FileWriter(path.toFile())) {
+            writer.write(representation);
+        }
+    }
+
+    private void writePlaceholders(Map<String, String> mapping, Path path) throws IOException {
+        LOGGER.info("Writing placeholder mapping to {}", path);
+        var sorted = new TreeMap<>(mapping);
+        try (var writer = new FileWriter(path.toFile())) {
+            writer.write(GSON.toJson(sorted));
+        }
+    }
+
+    private void writeMetadata(Path path) throws IOException {
+        LOGGER.info("Writing representation metadata to {}", path);
+        var json = new JsonObject();
+        json.addProperty("version", REPRESENTER_VERSION);
+        try (var writer = new FileWriter(path.toFile())) {
+            writer.write(GSON.toJson(json));
+        }
+    }
+}

src/main/java/representer/PlaceholderGenerator.java

@@ -0,0 +1,6 @@
+package representer;
+
+public interface PlaceholderGenerator {
+    boolean isPlaceholder(String identifier);
+    String getPlaceholder(String identifier);
+}

src/main/java/representer/Placeholders.java

@@ -0,0 +1,26 @@
+package representer;
+
+import java.util.HashMap;
+import java.util.Map;
+
+public class Placeholders implements PlaceholderGenerator {
+    private static final String PLACEHOLDER_PREFIX = "PLACEHOLDER";
+
+    private final Map<String, String> placeholders = new HashMap<>();
+
+    @Override
+    public boolean isPlaceholder(String identifier) {
+        return identifier.startsWith(PLACEHOLDER_PREFIX);
+    }
+
+    @Override
+    public String getPlaceholder(String identifier) {
+        var placeholder = String.format("%s_%02d", PLACEHOLDER_PREFIX, this.placeholders.size() + 1);
+        this.placeholders.put(placeholder, identifier);
+        return placeholder;
+    }
+
+    public Map<String, String> getPlaceholders() {
+        return Map.copyOf(this.placeholders);
+    }
+}