Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/saveourtool/benedikt

A GitHub Action to check your code with diKTat
https://github.com/saveourtool/benedikt

diktat github-actions reporting testing

Last synced: about 2 hours ago
JSON representation

A GitHub Action to check your code with diKTat

Host: GitHub
URL: https://github.com/saveourtool/benedikt
Owner: saveourtool
License: mit
Created: 2022-08-29T08:26:48.000Z (about 2 years ago)
Default Branch: master
Last Pushed: 2023-12-25T08:24:02.000Z (11 months ago)
Last Synced: 2024-10-31T07:42:19.963Z (7 days ago)
Topics: diktat, github-actions, reporting, testing
Homepage:
Size: 182 KB
Stars: 10
Watchers: 5
Forks: 2
Open Issues: 6
Metadata Files:
- Readme: README.adoc
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

= A _GitHub Action_ to check your code with https://github.com/saveourtool/diktat[_diKTat_]
:toc:
:imagesdir: docs/images
:tip-caption: pass:[💡]

[.float-group]
--
[.left]
image::https://img.shields.io/badge/License-MIT-yellow.svg[License: MIT,link="https://opensource.org/licenses/MIT"]

[.left]
image::https://badgen.net/github/release/saveourtool/benedikt/latest?color=green[GitHub release,link=https://github.com/saveourtool/benedikt/releases/latest]

[.left]
image::https://badgen.net/badge/icon/Ubuntu?icon=terminal&label&color=green[Ubuntu Linux]

[.left]
image::https://badgen.net/badge/icon/macOS?icon=apple&label&color=green[macOS]

[.left]
image::https://badgen.net/badge/icon/Windows?icon=windows&label&color=green[Windows]
--

[TIP]
====
An always updated version of this document is available
link:https://saveourtool.github.io/benedikt/ebook.pdf[here] as a PDF e-book.
====

== Features

* Customizable `diktat-analysis.yml` xref:#config[location]. You can use the
rule set configuration with an alternate name or at a non-default location.

* Customizable JVM xref:#java-setup[vendor and version]. You can run _diKTat_
using a default JVM, or you can set up your own one.

* Customizable xref:#reporter[reporter] (_SARIF_ or _Checkstyle_ XML).

* Allows multiple xref:#input-paths[input paths]. If you have a multi-module
project and only wish to check certain directories or modules, you can configure
the action accordingly.

* The summary page contains statistic about detected errors:
+
image::check-summary.png[diKTat Check summary]

== Usage

In the simplest scenario, the action can be used without input parameters; you
just need to check out your code first, using
https://github.com/marketplace/actions/checkout[`actions/checkout`]:

[source,yaml]
----
jobs:
diktat_check:
name: 'diKTat Check'
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v4

- uses: saveourtool/benedikt@v2
----

== Configuration

[#config]
=== `config`: custom configuration file

* Default: `diktat-analysis.yml`
* Required: **no**

You can override the name or the path of your YAML configuration file using the
`config` input parameter, e. g.:

[source,yaml]
----
- uses: saveourtool/benedikt@v2
with:
config: path/to/diktat-analysis-custom.yml
----

[#reporter]
=== `reporter`: requesting a type of reporter

If you wish, you can report errors in a different format.

* Default: `sarif`
* Required: **no**
* Possible values: any of the following.

** `sarif`: report errors in the
https://github.com/microsoft/sarif-tutorials/blob/main/docs/1-Introduction.md#what-is-sarif[_SARIF_]
format. The output file will be named `report.sarif` and automatically uploaded
to _GitHub_ using the https://github.com/github/codeql-action/tree/v2/upload-sarif[`upload-sarif`]
action. This will enable the check results to be shown as annotations in the
pull request:
+
image::sarif-reporting-pr.png[diKTat SARIF reporting (Pull Request)]
+
as well as in the _Code scanning alerts_ section of your repository:
+
image::sarif-reporting-code-scanning-alerts.png[diKTat SARIF reporting (Code scanning alerts)]

** `checkstyle`: this is the reporter of choice if you ever encounter issues
with the `sarif` reporter. Errors are reported in the
https://github.com/checkstyle/checkstyle[_Checkstyle-XML_] format to the file
named `checkstyle-report.xml`. The report is then consumed by the
https://github.com/reviewdog/reviewdog[`reviewdog`] tool and uploaded to
_GitHub_, resulting in code annotations similar to those produced by the `sarif`
reporter:
+
image::checkstyle-xml-reporting.png[Checkstyle-XML reporting assisted by reviewdog]

[#input-paths]
=== `input-paths`: custom source sets

* Default: none
* Required: **no**

One or more patterns which indicate the files or directories to check. Use a
multiline string to specify multiple inputs.

* If an input is a path to a file, it is passed to _diKTat_ as-is:
+
[source,yaml]
----
- uses: saveourtool/benedikt@v2
with:
input-paths: |
path/to/file.kt
----

* If an input is a path to a directory, the directory is recursively traversed,
and all `\*.kt` and `*.kts` files are passed to _diKTat_.
+
[source,yaml]
----
- uses: saveourtool/benedikt@v2
with:
input-paths: |
src/main/kotlin
src/test/kotlin
----
* If an input is an https://ant.apache.org/manual/dirtasks.html#patterns[_Ant_-style
path pattern] (such as `\\**/*.kt`), _diKTat_ expands it into the list of files
that match the path pattern. Path patterns may be negated, e. g.:
`!src/\**/*Test.kt` or `!src/\**/generated/**`.
+
[source,yaml]
----
- uses: saveourtool/benedikt@v2
with:
input-paths: |
**/*.kt
**/*.kts
!**/generated/**
----

If this input parameter is not specified, this is equivalent to setting it to
`.`, meaning _diKTat_ will check all `\*.kt` and `*.kts` files in the project
directory unless configured otherwise.

[#java-setup]
=== `java-distribution` and `java-version`: running _diKTat_ using a custom JVM

It's possible to run _diKTat_ with a custom JVM using the
https://github.com/actions/setup-java[`actions/setup-java`] action. The
following input parameters may be specified:

* `java-distribution`: the Java distribution, see the
https://github.com/actions/setup-java/blob/main/README.md#supported-distributions[list
of supported distributions].

** Default: `temurin`
** Required: **no**

* `java-version`: the Java version to set up. Takes a whole or semver Java
version. See https://github.com/actions/setup-java/blob/main/README.md#supported-version-syntax[examples
of supported syntax].

** Default: none
** Required: **no**

[NOTE]
Setting just the `java-distribution` property in order to use a custom
JDK is not sufficient: you'll need to set **both** `java-distribution` **and**
`java-version`:

[source,yaml]
----
- uses: saveourtool/benedikt@v2
with:
java-distribution: 'temurin'
java-version: 17
----

=== `fail-on-error`: suppressing lint errors

* Default: `true`
* Required: **no**

If `false`, the errors are still reported, but the step completes successfully.
If `true` (the default), then lint errors reported by _diKTat_ are considered
fatal (i.e. the current step terminates with a failure):

[source,yaml]
----
- uses: saveourtool/benedikt@v2
with:
fail-on-error: true
----

[NOTE]

This flag only affects the case when _diKTat_ exits with code **1**. Higher
link:https://diktat.saveourtool.com/diktat-cli/#exit-codes[exit
codes] are _always_ fatal.

=== `debug`: enabling debug logging

* Default: `false`
* Required: **no**

Debug logging can be enabled by setting the `debug` input parameter to `true`:

[source,yaml]
----
- uses: saveourtool/benedikt@v2
with:
debug: true
----

== Outputs

The action returns the exit code of the command-line client using the
`exit-code` output parameter, e. g.:

[source,yaml]
----
jobs:
diktat_check:
name: 'diKTat Check'
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v4

- id: diktat
uses: saveourtool/benedikt@v2

- name: 'Read the exit code of diKTat'
if: ${{ always() }}
run: echo "diKTat exited with code ${{ steps.diktat.outputs.exit-code }}"
shell: bash
----

The exit codes are documented
link:https://diktat.saveourtool.com/diktat-cli/#exit-codes[here].