From 5889e36200feea5785a58f1b51433e439a5bbffe Mon Sep 17 00:00:00 2001 From: jycr Date: Wed, 12 Apr 2023 03:28:25 +0200 Subject: [PATCH] green-code-initiative/ecoCode#92 feat(rule): Creates module `ecocode-rules-specifications` --- .../AboutRuleSpecification.md | 83 +++++++++++++ ecocode-rules-specifications/README.md | 22 ++++ .../SonarQubeIntegration.md | 45 +++++++ ecocode-rules-specifications/pom.xml | 110 ++++++++++++++++++ pom.xml | 1 + 5 files changed, 261 insertions(+) create mode 100644 ecocode-rules-specifications/AboutRuleSpecification.md create mode 100644 ecocode-rules-specifications/README.md create mode 100644 ecocode-rules-specifications/SonarQubeIntegration.md create mode 100644 ecocode-rules-specifications/pom.xml diff --git a/ecocode-rules-specifications/AboutRuleSpecification.md b/ecocode-rules-specifications/AboutRuleSpecification.md new file mode 100644 index 000000000..af09bc84e --- /dev/null +++ b/ecocode-rules-specifications/AboutRuleSpecification.md @@ -0,0 +1,83 @@ +# How to specify rules + +### Title + +The name of the rule. Must be very short (a few words) + +### ID + +The identifier of a rule is built like that: + +- Starts with: `EC` (for _ecoCode_ rule) +- Then number + +For example for the first leakage rule we have the id: `ELEA001` + +## Severity / Remediation Cost + +### Severity + +The severity can be seen as the impact of a rule in its category. Is it just a detail or is it fundamental ? +Here is an array to help choosing the severity level: + +| Severity | | +|----------|-----------------------------------------------------------------| +| Critical | Can be dramatic if not fix | +| Major | Important impact | +| Minor | Low impact | +| Info | Not really a problem but needed to be say | +| Helpful | Doing this will help to have a more eco-responsible application | + +### Remediation cost + +This is the evaluation of the cost of the remediation of the issue in a project. + +| Remediation Cost | | +|------------------|--------------------------------------------------------------------------------------------------------------------------| +| None | No cost - mainly for helpful rules | +| Trivial | No need to understand the logic and no potential impact (removing import, logs...) | +| Easy | No need to understand the logic but potential impacts | +| Medium | Understanding the logic of a piece of code is required before doing a little and easy refactoring (1 or 2 lines of code) | +| Major | Understanding the logic of a piece of code is required and it's up to the developer to define the remediation action | +| High | The remediation action might lead to locally impact the design of the application. | +| Complex | The remediation action might lead to an impact on the overall design of the application | + +## Rule short description + +The short description is a small sentence that quickly explain the impact of the rule to the user. +It must be short and should directly engage the user. + +eg. +> - Failing to call `release()` on a Media Player may lead to continuous battery consumption. +> - Forcing brightness to max value may cause useless energy consumption. + +## Rule complete description + +### Text + +The long description of the rule. It must explain the whole rule characteristics using the current language. + +### HTML + +The HTML version of the rule description. It may contain a Non-compliant and compliant code example. +Here is a template of the HTML description of a rule: + +```html +

My long rule description with some code in it.

+

Non-compliant Code Example

+
+MyCode code = new DirtCode();
+
+

Compliant Solution

+
+MyCode code = new GoodCode()
+
+``` + +## Implementation principle + +A description in current language on how to implement the rule based on an AST of the code. + +## Additional information + +* [Coding rule guidelines - SonarQube Docs](https://docs.sonarqube.org/latest/extension-guide/adding-coding-rules/#coding-rule-guidelines) diff --git a/ecocode-rules-specifications/README.md b/ecocode-rules-specifications/README.md new file mode 100644 index 000000000..c46f254d3 --- /dev/null +++ b/ecocode-rules-specifications/README.md @@ -0,0 +1,22 @@ +# ecoCode rules specification repository + +## Description + +This project contains the specifications of the ecoCode rules. + +## How to specify a rule + +To learn how to specify a rule, please follow the documentation: + +- [About Rule Specification](AboutRuleSpecification.md) +- [SonarQube Integration](SonarQubeIntegration.md) + +All the existing rules can be found in the [rules folder](src/main/rules). + +## Description language + +The description of the rules uses the ASCIIDOC format (with [Markdown compatibility](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#markdown-compatibility)) in order to allow the inclusion of other pages (this feature is not available in standard with Markdown). + +See: +* [AsciiDoc Syntax Quick Reference](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/) +* [Compare AsciiDoc to Markdown](https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/) diff --git a/ecocode-rules-specifications/SonarQubeIntegration.md b/ecocode-rules-specifications/SonarQubeIntegration.md new file mode 100644 index 000000000..ac0c2df8c --- /dev/null +++ b/ecocode-rules-specifications/SonarQubeIntegration.md @@ -0,0 +1,45 @@ +\newpage + +# Integrating a rule in SonarQube + +This document explain what to do to implement a rule from the specification in SonarQube, +where to use each specification elements and the naming conventions. + +*Emphasized* elements refer to elements described in [How to specify rules](AboutRuleSpecification.md#how-to-specify-rules). + +## Java + +### Rule class + +- Package: `io.ecocode.*language*.checks` +- Class Name: `*Title*Rule` +- `@Rule` Annotations: `@Rule(key = "ECxx")` (where `xx` are digits) + +### Test class + +- `Package`: same as class but in `src/test/java` folder +- `Class Name`: `*Title*RuleTest` + +### Rule description files (HTML and JSON) + +- **HTML** + - `Name`: *ID*_*language*.html -> **Sonar norm, will not work without that** + - `Content`: use the *HTML version of the description of the rule* +- **JSON** + - `Name`: *ID*_*language*.json -> **Sonar norm, will not work without that** + - `Content`: + - `Title`: *Subcategory*: *Title* (*Variant*) + - `Type`: CODE_SMELL + - `Status`: ready + - `Remediation` + - `func`: Constant/Issue + - `constantCost`: see following [remediation cost conversion array](#remediation-cost-conversion-array) + - `Tags`: *Category*, *Subcategory*, ecocode + - `Default Severity`: *Severity* (_Helpful_ must be set to _Info_) + + +## Remediation cost conversion array + +| Specification remediation | Trivial | Easy | Medium | Major | High | Complex | +|---------------------------|---------|-------|--------|-------|------|---------| +| SonarQube constant | 5min | 10min | 20min | 1h | 3h | 1d | diff --git a/ecocode-rules-specifications/pom.xml b/ecocode-rules-specifications/pom.xml new file mode 100644 index 000000000..13f5f135b --- /dev/null +++ b/ecocode-rules-specifications/pom.xml @@ -0,0 +1,110 @@ + + + 4.0.0 + + + io.ecocode + ecocode-parent + 1.2.2-SNAPSHOT + + + ecocode-rules-specifications + + ecoCode Rules Specifications repository + Repository that contains the specifications of every static-analysis rules available in ecoCode plugins. + https://github.com/green-code-initiative/ecoCode/tree/main/ecocode-rules-specifications + + + + org.sonarsource.sonarqube + sonar-plugin-api + provided + + + org.sonarsource.analyzer-commons + sonar-analyzer-commons + + + + org.junit.jupiter + junit-jupiter + test + + + + org.assertj + assertj-core + test + + + + + + + org.jacoco + jacoco-maven-plugin + + + prepare-agent + + prepare-agent + + + + report + + report + + + + + + org.asciidoctor + asciidoctor-maven-plugin + 2.2.4 + + + convert-to-html + generate-resources + + process-asciidoc + + + ${project.basedir}/src/main/rules + ${project.build.directory}/rules + + coderay + style + + true + false + true + + + ERROR + + + + + + + + org.apache.maven.plugins + maven-antrun-plugin + 3.1.0 + + + + + org.apache.maven.plugins + maven-assembly-plugin + 3.6.0 + + + + true + + + + + diff --git a/pom.xml b/pom.xml index bead6defc..65a2656d8 100644 --- a/pom.xml +++ b/pom.xml @@ -23,6 +23,7 @@ + ecocode-rules-specifications python-plugin java-plugin javascript-plugin