exercism / java-representer

Java Representer

This repository contains the source code for the Representer 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

If you want to contribute to the Java Representer, please refer to the Contributing Guide.

Usage

Running directly

Start by building the JAR using Gradle:

./gradlew build

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:

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:

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:

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:

./gradlew test

Smoke tests

To run the smoke tests using Docker:

bin/run-tests-in-docker.sh

java-representer's Issues

Normalize usage of `this`

It would be nice if the representer was able to normalize code such as the following two snippets into the same representation:

class SomeClass {
    private String someField = "";

    String getSomeField() {
        return someField;
    }

    void setSomeField(String someField) {
        this.someField = someField;
    }
}

class SomeClass {
    private String someField = "";

    String getSomeField() {
        return this.someField;
    }

    void setSomeField(String someField) {
        this.someField = someField;
    }
}

Right now, these variants both get their own representation because one uses this in getSomeField() while the other one doesn't. The easiest way to normalize would be to always add this when referencing instance fields or methods, since removing it will result in invalid code for setSomeField().

Analyze types of method parameters for substitution

Currently java-represent doesn't analyze types of method parameters to understand if they are user defined or not

Example extracted from Allergen exercise

boolean PLACEHOLDER_15(Allergen PLACEHOLDER_16) 
    {
        return (PLACEHOLDER_10 & PLACEHOLDER_17.getScore()) != 0;
    }

missing placeholder substitution in variable definition

Application doesn't substitute placeholder into a variable definition

Example

List<T> newCollection = new ArrayList<>();

Wrong representation.txt for accumulate exercise

class PLACEHOLDER_1
{

    static <T> List<T> PLACEHOLDER_2(List<T> PLACEHOLDER_6, Function<T, T> PLACEHOLDER_4) 
    {
        List<T> newCollection = new ArrayList<>();
        for (T item : PLACEHOLDER_6) 
        {
            PLACEHOLDER_5.add(PLACEHOLDER_4.apply(PLACEHOLDER_3));
        }
        return PLACEHOLDER_5;
    }
}

uncorrect placeholder substitution of "this" variables

At the moment variables expressed as

this.numeral = computeNumeral(PLACEHOLDER_2, PLACEHOLDER_3);

are not correctly substituted

Enum is not correctly replaced by a placeholder

The enum name isn't substituted by a placeholder

Example of representation of allergies exercise

enum Allergen {

    EGGS(1),
    PEANUTS(2),
    SHELLFISH(4),
    STRAWBERRIES(8),
    TOMATOES(16),
    CHOCOLATE(32),
    POLLEN(64),
    CATS(128);

    private final int PLACEHOLDER_1;

    PLACEHOLDER_2(int PLACEHOLDER_1)
    {
        this.PLACEHOLDER_1 = PLACEHOLDER_1;
    }

    int PLACEHOLDER_3()
    {
        return PLACEHOLDER_1;
    }                                                                                                                                                                                                              
}                                                                                                                                                                                                                  
class PLACEHOLDER_4                                                                                                                                                                                                
{                                                                                                                                                                                                                  
                                                                                                                                                                                                                   
    private int PLACEHOLDER_1;                                                                                                                                                                                     
                                                                                                                                                                                                                   
    PLACEHOLDER_4(int PLACEHOLDER_1)                                                                                                                                                                               
    {                                                                                                                                                                                                              
        this.PLACEHOLDER_1 = PLACEHOLDER_1;                                                                                                                                                                        
    }                                                                                                                                                                                                              
                                                                                                                                                                                                                   
    List<Allergen> PLACEHOLDER_5()                                                                                                                                                                                 
    {                                                                                                                                                                                                              
        return PLACEHOLDER_7.allOf(Allergen.class).stream().filter(this::isAllergicTo).collect(PLACEHOLDER_6.toList());                                                                                            
    }                                                                                                                                                                                                              
                                                                                                                                                                                                                   
    boolean PLACEHOLDER_8(Allergen PLACEHOLDER_9)                                                                                                                                                                  
    {                                                                                                                                                                                                              
        return (PLACEHOLDER_1 & PLACEHOLDER_9.getScore()) != 0;                                                                                                                                                    
    }                                                                                                                                                                                                              
}          

Errors in parsing version JSON file

We're getting the following error in production:

unexpected characters after the JSON document (after ) at line 2, column 1 [parse.c:731] in '{"version": 1} {"version": 1} {"version": 1} {"version": 1}

Analyze MyClass.class for substitution

Currently java-representer doesn't analyze MyClass.class format to understand if MyClass is user-defined or not

Here an example extracted from Allergen exercise

 List<PLACEHOLDER_1> PLACEHOLDER_14() 
    {
        return EnumSet.allOf(Allergen.class).stream().filter(this::isAllergicTo).collect(Collectors.toList());
    }

representation isn't fully compliant with the requirements

The java-parser lib used by the java-representer prints the block representation as

block {
  ...inside code
}

the requirement is to output blocks as

block
{
  ...inside code
}

Build and push docker image error

Failure during the step Build and push Docker image

with this message
buildx call failed with: failed to solve: rpc error: code = Unknown desc = server message: insufficient_scope: authorization failed

Java-representer doesn't understand what is user defined

At the moment the java-representer is not able to understand if a class or interface is user-defined or provided by the language.
So java-representer replaces with placeholder too much "names"

For example Arrays.asList() is replaced by placeholder ( PLACEHOLDER_1.asList()) even if Arrays is a class provided by Java

solution composed by multiple source files

At the moment application assumes that solution consists in an only source file.

There are some exercises in the Java track that consist in more files. (Problem allergies for example)

Comment format not removed

Currently java-representer doesn't remove the comment format like this:

 /**
    * Returns true if the mapping letters to digits using {@code letterToDigit} will result in having zero as a
   * leading digit.
    */

The master branch will be renamed to main

In line with our new org-wide policy, the master branch of this repo will be renamed to main. All open PRs will be automatically repointed.

GitHub will show you a notification about this when you look at this repo after renaming:

In case it doesn't, this is the command it suggests:

git branch -m master main
git fetch origin
git branch -u origin/main main

You may like to update the primary branch on your forks too, which you can do under Settings->Branches and clicking the pencil icon on the right-hand-side under Default Branch:

We will post a comment below when this is done. We expect it to happen within the next 12 hours.