green-code-initiative#92 feat(rule): Creates module `ecocode-rules-sp…

…ecifications`

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
+<p>My long rule description with some <code>code</code> in it.</p>
+<h2>Non-compliant Code Example</h2>
+<pre>
+MyCode code = new DirtCode();
+</pre>
+<h2>Compliant Solution</h2>
+<pre>
+MyCode code = new GoodCode()
+</pre>
+```
+
+## 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)

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/)

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      |

ecocode-rules-specifications/pom.xml

@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<groupId>io.ecocode</groupId>
+		<artifactId>ecocode-parent</artifactId>
+		<version>1.2.2-SNAPSHOT</version>
+	</parent>
+
+	<artifactId>ecocode-rules-specifications</artifactId>
+
+	<name>ecoCode Rules Specifications repository</name>
+	<description>Repository that contains the specifications of every static-analysis rules available in ecoCode plugins.</description>
+	<url>https://github.com/green-code-initiative/ecoCode/tree/main/ecocode-rules-specifications</url>
+
+	<dependencies>
+		<dependency>
+			<groupId>org.sonarsource.sonarqube</groupId>
+			<artifactId>sonar-plugin-api</artifactId>
+			<scope>provided</scope>
+		</dependency>
+		<dependency>
+			<groupId>org.sonarsource.analyzer-commons</groupId>
+			<artifactId>sonar-analyzer-commons</artifactId>
+		</dependency>
+
+		<dependency>
+			<groupId>org.junit.jupiter</groupId>
+			<artifactId>junit-jupiter</artifactId>
+			<scope>test</scope>
+		</dependency>
+
+		<dependency>
+			<groupId>org.assertj</groupId>
+			<artifactId>assertj-core</artifactId>
+			<scope>test</scope>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.jacoco</groupId>
+				<artifactId>jacoco-maven-plugin</artifactId>
+				<executions>
+					<execution>
+						<id>prepare-agent</id>
+						<goals>
+							<goal>prepare-agent</goal>
+						</goals>
+					</execution>
+					<execution>
+						<id>report</id>
+						<goals>
+							<goal>report</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+			<plugin>
+				<groupId>org.asciidoctor</groupId>
+				<artifactId>asciidoctor-maven-plugin</artifactId>
+				<version>2.2.4</version>
+				<executions>
+					<execution>
+						<id>convert-to-html</id>
+						<phase>generate-resources</phase>
+						<goals>
+							<goal>process-asciidoc</goal>
+						</goals>
+						<configuration>
+							<sourceDirectory>${project.basedir}/src/main/rules</sourceDirectory>
+							<outputDirectory>${project.build.directory}/rules</outputDirectory>
+							<attributes>
+								<source-highlighter>coderay</source-highlighter>
+								<coderay-css>style</coderay-css>
+							</attributes>
+							<preserveDirectories>true</preserveDirectories>
+							<headerFooter>false</headerFooter>
+							<relativeBaseDir>true</relativeBaseDir>
+							<logHandler>
+								<failIf>
+									<severity>ERROR</severity>
+								</failIf>
+							</logHandler>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-antrun-plugin</artifactId>
+				<version>3.1.0</version>
+				<executions>
+				</executions>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-assembly-plugin</artifactId>
+				<version>3.6.0</version>
+				<executions>
+				</executions>
+				<configuration>
+					<appendAssemblyId>true</appendAssemblyId>
+				</configuration>
+			</plugin>
+		</plugins>
+	</build>
+</project>

pom.xml

@@ -23,6 +23,7 @@
     </licenses>
 
     <modules>
+        <module>ecocode-rules-specifications</module>
         <module>python-plugin</module>
         <module>java-plugin</module>
         <module>javascript-plugin</module>