Add documentation for SARIF, severity and relative path (#3433)

* Add documentation for SARIF, severity and relative path

* Reduce redundancy and fix text in configurations.

README.md

@@ -97,7 +97,7 @@ detekt {
         html.enabled = true // observe findings in your browser with structure and code snippets
         xml.enabled = true // checkstyle like format mainly for integrations like Jenkins
         txt.enabled = true // similar to the console output, contains issue signature to manually edit baseline files
-        sarif.enabled = true // SARIF integration (https://sarifweb.azurewebsites.net/) for integrations with Github
+        sarif.enabled = true // standardized SARIF format (https://sarifweb.azurewebsites.net/) to support integrations with Github Code Scanning
     }
 }
 

buildSrc/src/main/kotlin/detekt.gradle.kts

@@ -40,6 +40,7 @@ subprojects {
             xml.enabled = true
             html.enabled = true
             txt.enabled = true
+            sarif.enabled = true
         }
     }
 

docs/_data/sidebars/home_sidebar.yml

@@ -20,6 +20,9 @@ entries:
     - title: Configuration File
       url: /configurations.html
       output: web
+    - title: Reporting
+      url: /reporting.html
+      output: web
     - title: Suppressing Issues in Code
       url: /suppressing-rules.html
       output: web

docs/pages/configurations.md

@@ -100,7 +100,7 @@ The rule violations are grouped by file location.
 
 ## Output Reports
 
-Uncomment the reports you don't care about.
+Uncomment the reports you don't care about. The detailed description can be found in [reporting](reporting.md).
 
 ```yaml
 output-reports:
@@ -112,17 +112,6 @@ output-reports:
   #  - 'SarifOutputReport'
 ```
 
-**HtmlOutputReport** contains rule violations and metrics formatted in a human friendly way, so that it can be inspected in a web browser.
-
-**TxtOutputReport** contains rule violations in a plain text report similar to a log file.
-
-**XmlOutputReport** contains rule violations in an XML format. The report follows the structure of a [Checkstyle report](https://checkstyle.sourceforge.io).
-
-**SarifOutputReport** contains rule violations in the SARIF format. Please check [SARIF](https://sarifweb.azurewebsites.net/).
-
-Rule violations show the name of the violated rule and in which file the issue happened.
-The mentioned metrics show detailed statistics concerning the analyzed code.
-For instance the source lines of code and the McCabe complexity are calculated.
 
 ## Processors
 

docs/pages/reporting.md

@@ -0,0 +1,104 @@
+---
+title: "Reporting"
+keywords: reporting
+sidebar: 
+permalink: reporting.html
+summary: This page describes each reporting format and explains how to leverage them.
+---
+
+## Formats
+
+In addition to the CLI output, Detekt supports 4 different types of output reporting formats.
+You can refer to [CLI](gettingstarted/cli.md) or [Gradle](gettingstarted/gradle.md) to find
+out how to configure these report formats.
+
+### TXT
+Similar to the console output, each line of the txt output represents a finding and contains
+finding signature to help edit [baseline files](gettingstarted/gradle.md).
+
+```
+EmptyFunctionBlock - [apply] at /Users/cazhang/detekt/detekt-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/DetektPlugin.kt:14:42 - Signature=DetektPlugin.kt$DetektPlugin${ }
+NoUnusedImports - [] at /Users/cazhang/detekt/detekt-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/DetektPlugin.kt:9:1 - Signature=io.gitlab.arturbosch.detekt.DetektPlugin.kt:9
+NoUnusedImports - [] at /Users/cazhang/detekt/detekt-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/DetektPlugin.kt:10:1 - Signature=io.gitlab.arturbosch.detekt.DetektPlugin.kt:10
+NoConsecutiveBlankLines - [] at /Users/cazhang/detekt/detekt-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/DetektPlugin.kt:86:1 - Signature=io.gitlab.arturbosch.detekt.DetektPlugin.kt:86
+UnusedPrivateMember - [registerDetektJvmTasks] at /Users/cazhang/detekt/detekt-gradle-plugin/src/main/kotlin/io/gitlab/arturbosch/detekt/DetektPlugin.kt:17:5 - Signature=DetektPlugin.kt$DetektPlugin$private fun Project.registerDetektJvmTasks(extension: DetektExtension)
+```
+
+### HTML
+HTML is a human-readable format that can be open through browser. It includes different metrics
+and complexity reports of this run, in addition to the findings with detailed descriptions and
+report. Check out the example: ![HTML report](images/reporting/html.png).
+
+### XML
+XML is a machine-readable format that can be integrated with CI tools. It is compatible with
+[Checkstyle](https://checkstyle.sourceforge.io/) output.
+
+### SARIF
+[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.
+
+## Severity
+For machine-readable format, it is possible to configure the severity of each finding to fit
+your CI policy with respects to errors. You may specify the severity level in the config file
+for rule, or ruleSets:
+
+```yaml
+empty-blocks:
+  active: true
+  severity: error
+  EmptyCatchBlock:
+    active: true
+    severity: info
+```
+
+The severity will be computed in the priority order:
+- Severity of the rule if exists
+- Severity of the parent ruleset if exists
+- Default severity: warning
+
+## Relative path
+In a shared codebase, it is often required to use relative path so that all developers and tooling
+have a consistent view. This can be enabled by CLI option `--base-path` or Gradle as the following:
+
+```groovy
+detekt {
+    basePath = projectDir
+}
+```
+
+Note that this option only affects file paths in those formats for machine consumers,
+namely XML and SARIF.
+
+## Integration with Github Code Scanning
+If your repository is hosted on Github, you can enable SARIF output in your repository.
+You can follow to the [official documentation](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/uploading-a-sarif-file-to-github).
+
+You can follow the example below as a quick start:
+```yaml
+jobs:
+  without-type-resolution:
+    runs-on: ubuntu-latest
+    env:
+      GRADLE_OPTS: -Dorg.gradle.daemon=false
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+
+      - name: Setup Java
+        uses: actions/setup-java@v1
+        with:
+          java-version: 11
+
+      - name: Run detekt
+        run: ./gradlew detekt
+
+      # Make sure we always run this upload task, because the previous step fails if there are
+      # findings.
+      - name: Upload SARIF to Github using the upload-sarif action
+        uses: github/codeql-action/upload-sarif@v1
+        if: ${{ always() }}
+        with:
+          sarif_file: build/detekt.sarif
+```