diff --git a/README.md b/README.md index b6b29be..d0f0c0d 100644 --- a/README.md +++ b/README.md @@ -165,34 +165,40 @@ For detailed usage instructions, command-line options, and examples, including t The generated markdown report includes: -1. **Quality Gate Status** - Overall pass/fail status -2. **Quality Gate Conditions** - Detailed conditions with thresholds and actual values -3. **Issues** - Open and confirmed issues grouped by type (bugs, code smells, vulnerabilities) and severity -4. **Security Hot-Spots** - Security vulnerabilities requiring review +1. **Project Header** - Project name and dashboard link +2. **Quality Gate Status** - Overall pass/fail status (OK, ERROR, WARN, or NONE) +3. **Conditions** - Detailed quality gate conditions with metrics, comparators, thresholds, and actual values +4. **Issues** - Count and list of issues in compiler-style format with file, line, severity, type, rule, and message +5. **Security Hot-Spots** - Count and list of security vulnerabilities requiring review in compiler-style format Example report structure: ```markdown -# Quality Gate Status +# Example Project Sonar Analysis -**Status**: PASSED +**Dashboard:** -## Quality Gate Conditions +**Quality Gate Status:** ERROR -| Condition | Status | Actual | Threshold | -|-----------|--------|--------|-----------| -| Coverage | OK | 85.2% | > 80% | -| Duplications | OK | 2.1% | < 3% | +## Conditions + +| Metric | Status | Comparator | Threshold | Actual | +|:-------------------------------|:-----:|:--:|--------:|-------:| +| Coverage on New Code | ERROR | LT | 80 | 65.5 | +| New Bugs | ERROR | GT | 0 | 3 | ## Issues -### Bugs -- **Major**: 2 -- **Minor**: 5 +Found 2 issues + +src/Program.cs(42): MAJOR CODE_SMELL [csharpsquid:S1234] Remove this unused variable +src/Helper.cs(15): MINOR CODE_SMELL [csharpsquid:S5678] Refactor this method + +## Security Hot-Spots + +Found 1 security hot-spot -### Code Smells -- **Major**: 15 -- **Minor**: 32 +src/Database.cs(88): HIGH [sql-injection] Make sure using this SQL query is safe ``` ## Contributing diff --git a/docs/guide/guide.md b/docs/guide/guide.md index 2b9be1e..62372a2 100644 --- a/docs/guide/guide.md +++ b/docs/guide/guide.md @@ -323,70 +323,106 @@ sonarmark --server https://sonarcloud.io \ The generated markdown report includes the following sections: -### Quality Gate Status +### Project Header -Shows whether the project passed or failed the quality gate: +The report begins with the project name and a link to the SonarQube/SonarCloud dashboard: ```markdown -# Quality Gate Status +# Example Project Sonar Analysis -**Status**: PASSED +**Dashboard:** ``` -or +### Quality Gate Status + +Shows whether the project passed or failed the quality gate. Possible values are OK, ERROR, WARN, or NONE: ```markdown -# Quality Gate Status +**Quality Gate Status:** OK +``` + +or -**Status**: ERROR +```markdown +**Quality Gate Status:** ERROR ``` -### Quality Gate Conditions +### Conditions + +If quality gate conditions exist, they are displayed in a table with the following columns: -Details of each quality gate condition with actual values and thresholds: +- **Metric**: The friendly name of the metric being measured (e.g., "Coverage on New Code") +- **Status**: The condition status (OK, ERROR, or WARN) +- **Comparator**: The comparison operator (LT for less than, GT for greater than) +- **Threshold**: The threshold value that was set +- **Actual**: The actual measured value ```markdown -## Quality Gate Conditions +## Conditions -| Condition | Status | Actual | Threshold | -|-----------|--------|--------|-----------| -| Coverage | OK | 85.2% | > 80% | -| Duplications | OK | 2.1% | < 3% | -| Security Rating | ERROR | E | A | +| Metric | Status | Comparator | Threshold | Actual | +|:-------------------------------|:-----:|:--:|--------:|-------:| +| Coverage on New Code | ERROR | LT | 80 | 65.5 | +| New Bugs | ERROR | GT | 0 | 3 | +| Duplications | OK | LT | 3 | 2.1 | ``` ### Issues -Issues are grouped by type and severity: +The issues section shows a count of issues found and lists each issue in compiler-style format: ```markdown ## Issues -### Bugs -- **Critical**: 0 -- **Major**: 2 -- **Minor**: 5 +Found 3 issues + +src/Program.cs(42): MAJOR CODE_SMELL [csharpsquid:S1234] Remove this unused variable +src/Helper.cs(15): MINOR CODE_SMELL [csharpsquid:S5678] Refactor this method to reduce complexity +src/Service.cs(88): MAJOR BUG [csharpsquid:S9012] Fix this potential null reference +``` + +Each issue line includes: + +- **File path and line number**: `src/Program.cs(42)` or just `src/Program.cs` if no line number +- **Severity**: BLOCKER, CRITICAL, MAJOR, MINOR, or INFO +- **Type**: BUG, VULNERABILITY, or CODE_SMELL +- **Rule**: The SonarQube rule identifier in brackets +- **Message**: Description of the issue -### Code Smells -- **Major**: 15 -- **Minor**: 32 +If no issues are found: -### Vulnerabilities -- **High**: 1 -- **Medium**: 3 +```markdown +## Issues + +Found no issues ``` ### Security Hot-Spots -Security vulnerabilities requiring review: +The security hot-spots section shows a count and lists each hot-spot in compiler-style format: + +```markdown +## Security Hot-Spots + +Found 2 security hot-spots + +src/Database.cs(88): HIGH [sql-injection] Make sure using this SQL query is safe +src/Auth.cs(42): MEDIUM [weak-cryptography] Use a stronger encryption algorithm +``` + +Each hot-spot line includes: + +- **File path and line number**: `src/Database.cs(88)` or just `src/Database.cs` if no line number +- **Vulnerability Probability**: HIGH, MEDIUM, or LOW +- **Security Category**: The type of security issue in brackets (e.g., sql-injection, weak-cryptography) +- **Message**: Description of the security concern + +If no security hot-spots are found: ```markdown ## Security Hot-Spots -| Priority | File | Line | Message | -|----------|------|------|---------| -| HIGH | src/Auth.cs | 42 | Make sure this authentication is safe | -| MEDIUM | src/Database.cs | 156 | Make sure this SQL query is safe | +Found no security hot-spots ``` ## Running Self-Validation