Support markdown report in Gradle plugin (#4995)

* Support markdown report in Gradle plugin * Add markdown description to website docs * Improve markdown description for website docs
detekt · Jun 27, 2022 · 3b7cae1 · 3b7cae1
1 parent 4441bc4
commit 3b7cae1
Show file tree

Hide file tree

Showing 13 changed files with 37 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -76,6 +76,7 @@ tasks.withType<Detekt>().configureEach {
         xml.required.set(true) // checkstyle like format mainly for integrations like Jenkins
         txt.required.set(true) // similar to the console output, contains issue signature to manually edit baseline files
         sarif.required.set(true) // standardized SARIF format (https://sarifweb.azurewebsites.net/) to support integrations with Github Code Scanning
+        md.required.set(true) // simple Markdown format
     }
 }
 

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -36,6 +36,7 @@ allprojects {
             html.required.set(true)
             txt.required.set(true)
             sarif.required.set(true)
+            md.required.set(true)
         }
     }
     tasks.withType<DetektCreateBaselineTask>().configureEach {
@@ -70,6 +71,7 @@ val detektFormat by tasks.registering(Detekt::class) {
         xml.required.set(false)
         html.required.set(false)
         txt.required.set(false)
+        md.required.set(false)
     }
 }
 
@@ -88,6 +90,7 @@ val detektAll by tasks.registering(Detekt::class) {
         xml.required.set(false)
         html.required.set(false)
         txt.required.set(false)
+        md.required.set(false)
     }
 }
 

diff --git a/code-coverage-report/build.gradle.kts b/code-coverage-report/build.gradle.kts
@@ -26,6 +26,7 @@ dependencies {
     jacocoAggregation(projects.detektReportSarif)
     jacocoAggregation(projects.detektReportTxt)
     jacocoAggregation(projects.detektReportXml)
+    jacocoAggregation(projects.detektReportMd)
     jacocoAggregation(projects.detektRules)
     jacocoAggregation(projects.detektRulesComplexity)
     jacocoAggregation(projects.detektRulesCoroutines)

diff --git a/detekt-cli/src/main/kotlin/io/gitlab/arturbosch/detekt/cli/CliArgs.kt b/detekt-cli/src/main/kotlin/io/gitlab/arturbosch/detekt/cli/CliArgs.kt
@@ -79,7 +79,7 @@ class CliArgs {
         names = ["--report", "-r"],
         description = "Generates a report for given 'report-id' and stores it on given 'path'. " +
             "Entry should consist of: [report-id:path]. " +
-            "Available 'report-id' values: 'txt', 'xml', 'html', 'sarif'. " +
+            "Available 'report-id' values: 'txt', 'xml', 'html', 'md', 'sarif'. " +
             "These can also be used in combination with each other " +
             "e.g. '-r txt:reports/detekt.txt -r xml:reports/detekt.xml'"
     )

diff --git a/...-gradle-plugin/src/functionalTest/kotlin/io/gitlab/arturbosch/detekt/DetektTaskDslSpec.kt b/...-gradle-plugin/src/functionalTest/kotlin/io/gitlab/arturbosch/detekt/DetektTaskDslSpec.kt
@@ -321,6 +321,9 @@ class DetektTaskDslSpec {
                     |        sarif {
                     |            enabled = false
                     |        }
+                    |        md {
+                    |            enabled = false
+                    |        }
                     |    }
                     |}
             """

diff --git a/detekt-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/Detekt.kt b/detekt-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/Detekt.kt
@@ -189,6 +189,11 @@ open class Detekt @Inject constructor(
         @Optional
         get() = getTargetFileProvider(reports.sarif)
 
+    val mdReportFile: Provider<RegularFile>
+        @OutputFile
+        @Optional
+        get() = getTargetFileProvider(reports.md)
+
     internal val customReportFiles: ConfigurableFileCollection
         @OutputFiles
         @Optional
@@ -217,6 +222,7 @@ open class Detekt @Inject constructor(
             DefaultReportArgument(DetektReportType.HTML, htmlReportFile.orNull),
             DefaultReportArgument(DetektReportType.TXT, txtReportFile.orNull),
             DefaultReportArgument(DetektReportType.SARIF, sarifReportFile.orNull),
+            DefaultReportArgument(DetektReportType.MD, mdReportFile.orNull),
             DebugArgument(debugProp.getOrElse(false)),
             ParallelArgument(parallelProp.getOrElse(false)),
             BuildUponDefaultConfigArgument(buildUponDefaultConfigProp.getOrElse(false)),

diff --git a/...-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/extensions/DetektReportType.kt b/...-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/extensions/DetektReportType.kt
@@ -5,7 +5,8 @@ enum class DetektReportType(val reportId: String, val extension: String) {
     XML("xml", "xml"),
     HTML("html", "html"),
     TXT("txt", "txt"),
-    SARIF("sarif", "sarif");
+    SARIF("sarif", "sarif"),
+    MD("md", "md");
 
     companion object {
         fun isWellKnownReportId(reportId: String) = reportId in values().map(DetektReportType::reportId)

diff --git a/detekt-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/extensions/DetektReports.kt b/detekt-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/extensions/DetektReports.kt
@@ -1,6 +1,7 @@
 package io.gitlab.arturbosch.detekt.extensions
 
 import io.gitlab.arturbosch.detekt.extensions.DetektReportType.HTML
+import io.gitlab.arturbosch.detekt.extensions.DetektReportType.MD
 import io.gitlab.arturbosch.detekt.extensions.DetektReportType.SARIF
 import io.gitlab.arturbosch.detekt.extensions.DetektReportType.TXT
 import io.gitlab.arturbosch.detekt.extensions.DetektReportType.XML
@@ -19,6 +20,8 @@ open class DetektReports @Inject constructor(val objects: ObjectFactory) {
 
     val sarif: DetektReport = objects.newInstance(DetektReport::class.java, SARIF)
 
+    val md: DetektReport = objects.newInstance(DetektReport::class.java, MD)
+
     val custom = mutableListOf<CustomDetektReport>()
 
     fun xml(action: Action<in DetektReport>): Unit = action.execute(xml)
@@ -29,6 +32,8 @@ open class DetektReports @Inject constructor(val objects: ObjectFactory) {
 
     fun sarif(action: Action<in DetektReport>): Unit = action.execute(sarif)
 
+    fun md(action: Action<in DetektReport>): Unit = action.execute(md)
+
     fun custom(action: Action<in CustomDetektReport>): Unit = action.execute(createAndAddCustomReport())
 
     private fun createAndAddCustomReport() =

diff --git a/...gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/internal/DetektMultiplatform.kt b/...gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/internal/DetektMultiplatform.kt
@@ -145,6 +145,7 @@ internal fun Project.setReportOutputConventions(reports: DetektReports, extensio
     setReportOutputConvention(extension, reports.html, name, "html")
     setReportOutputConvention(extension, reports.txt, name, "txt")
     setReportOutputConvention(extension, reports.sarif, name, "sarif")
+    setReportOutputConvention(extension, reports.md, name, "md")
 }
 
 private fun Project.setReportOutputConvention(

diff --git a/website/docs/gettingstarted/gradle.mdx b/website/docs/gettingstarted/gradle.mdx
@@ -21,7 +21,7 @@ The detekt Gradle plugin will generate multiple tasks:
   - By default, the standard rule set without any ignore list is executed on sources files located
    in `src/main/java`, `src/test/java`, `src/main/kotlin` and `src/test/kotlin`.
   - Reports are automatically generated in xml,
-   html, txt, and sarif format and can be found in `build/reports/detekt/detekt.[xml|html|txt|sarif]` respectively.
+   html, txt, md, and sarif format and can be found in `build/reports/detekt/detekt.[xml|html|txt|md|sarif]` respectively.
   - Please note that the `detekt` task is automatically run when executing `gradle check`.
   - You may specify Gradle task CLI option for auto correction, such as `gradle detekt --auto-correct`.
 - `detektGenerateConfig` - Generates a default detekt configuration file into your project directory.
@@ -48,7 +48,7 @@ the name of the build variant in their name, unless otherwise configured, such a
 `detekt-productionDebug.xml`.
 
 If both, a `detekt-main.xml` and a `detekt.xml` baseline file exists in place, the more specific one - `detekt-main.xml` -
-takes precendence when the `detektMain` task is executed, likewise for Android variant-specific baseline files.
+takes precedence when the `detektMain` task is executed, likewise for Android variant-specific baseline files.
 
 _NOTE:_ When analyzing Android projects that make use of specific code generators, such as Data Binding, Kotlin synthetic
 view accessors or else, you might see warnings output while Detekt runs. This is due to the inability to gather the
@@ -318,6 +318,9 @@ tasks.named("detekt").configure {
         // Enable/Disable SARIF report (default: false)
         sarif.required.set(true)
         sarif.outputLocation.set(file("build/reports/detekt.sarif"))
+        // Enable/Disable MD report (default: false)
+        md.required.set(true)
+        md.outputLocation.set(file("build/reports/detekt.md"))
         custom {
             // The simple class name of your custom report.
             reportId = "CustomJsonReport"

diff --git a/website/docs/intro.mdx b/website/docs/intro.mdx
@@ -68,6 +68,7 @@ tasks.withType<Detekt>().configureEach {
         html.required.set(true)
         txt.required.set(true)
         sarif.required.set(true)
+        md.required.set(true)
     }
 }
 ```
@@ -80,6 +81,7 @@ tasks.withType(Detekt).configureEach {
         html.required.set(true)
         txt.required.set(true)
         sarif.required.set(true)
+        md.required.set(true)
     }
 }
 ```

diff --git a/website/docs/introduction/configurations.md b/website/docs/introduction/configurations.md
@@ -126,6 +126,7 @@ output-reports:
   #  - 'TxtOutputReport'
   #  - 'XmlOutputReport'
   #  - 'SarifOutputReport'
+  #  - 'MdOutputReport'
 ```
 
 

diff --git a/website/docs/introduction/reporting.md b/website/docs/introduction/reporting.md
@@ -37,7 +37,12 @@ XML is a machine-readable format that can be integrated with CI tools. It is com
 [SARIF](https://sarifweb.azurewebsites.net/) is a standard format for the output of 
 static analysis tools. It is a JSON format with a defined 
 [schema](https://docs.oasis-open.org/sarif/sarif/v2.0/csprd02/schemas/). It is currently supported
-by Github Code Scanning and we expect more consuming tools will be adopt this format in the future.
+by GitHub Code Scanning, and we expect more consuming tools will adopt this format in the future.
+
+### MD
+Markdown is a lightweight markup language for creating formatted text using a plain-text editor.
+The output structure looks similar to HTML format.
+About [markdown](https://github.github.com/gfm/#what-is-markdown-) on GitHub.
 
 ## Severity
 For machine-readable format, it is possible to configure the severity of each finding to fit