# JavaCheckStyle

Stage for Java static analysis via [Checkstyle](https://checkstyle.sourceforge.io/).

- Kind: Pre-Grading Stage
- Behavior: Runs Checkstyle against a given list of files.

## Config

```
javaCheckStyle:
  input: [String]             # List of files to run Checkstyle over
  configFile: String          # Configuration file for Checkstyle
  classpath: [String]?        # Additional classpath(s) to provide to the Java VM [default: []]
  jvmArgs: [String]?          # Other arguments to provide to the Java VM [default: []]
  args: [String]?             # Other arguments to provide to Checkstyle [default: []]
  version: String?            # Checkstyle version to use [default: 8.33]
  scorePolicy: ScorePolicy?   # The scoring policy for this stage
```

A list of sample configuration files can be found [here](https://github.com/checkstyle/checkstyle/tree/master/config). 
Note that Checkstyle configuration files are not backward compatible, meaning that newer configuration formats may not 
be supported by older versions of the application. Therefore, it is advised to checkout the appropriate tag before 
downloading and/or modifying the configuration files.


This stage implements *Per-Element Scoring*; An element is defined as one single diagnostic emitted by Checkstyle. See 
[Scorable.md](../Scorable.md) for more information.

## Report

```
javaCheckStyle:
  - hasTimedOut: Boolean            # Whether the execution has timed out
    exitCode: Int                   # The exit code of the application.
    stderr: [String]                # Standard error output, if any.
    score: Score?                   # Scoring information of this stage.
    report: JavaCheckStyleXMLFile?  # XML report emitted by Checkstyle
```

[Example](examples/checkstyle_report.yaml)

### `JavaCheckStyleXMLFile`

`JavaCheckStyleXMLFile` is the internal name for the XML report emitted by Checkstyle's 
[XMLLogger](https://checkstyle.sourceforge.io/apidocs/com/puppycrawl/tools/checkstyle/XMLLogger.html).

```
files: [File]       # List of all files processed by Checkstyle

File:
  name: String      # Absolute path of the file
  errors: [Error]   # List of errors detected

Error:
  line: Int         # Line number of the error
  column: Int?      # Column number of the error. Null means that the error covers the entire line
  severity: String  # Error severity. See https://checkstyle.sourceforge.io/property_types.html#SeverityLevel
  message: String   # Human-friendly message of this warning
  source: String    # Checkstyle diagnostic class name
```