Skip to content

Commit

Permalink
green-code-initiative#92 feat(rule): Creates module `ecocode-rules-sp…
Browse files Browse the repository at this point in the history 
…ecifications`
  • Loading branch information
@jycr
jycr committed Jun 9, 2023
1 parent 75d1b0a commit c82dc7b
Show file tree
Hide file tree
Showing 5 changed files with 231 additions and 0 deletions.
83 changes: 83 additions & 0 deletions ecocode-rules-specifications/AboutRuleSpecification.md
View file
Original file line number Diff line number Diff line change
@@ -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)
22 changes: 22 additions & 0 deletions ecocode-rules-specifications/README.md
View file
Original file line number Diff line number Diff line change
@@ -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/)
45 changes: 45 additions & 0 deletions ecocode-rules-specifications/SonarQubeIntegration.md
View file
Original file line number Diff line number Diff line change
@@ -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 |
80 changes: 80 additions & 0 deletions ecocode-rules-specifications/pom.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
<?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>

<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<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>
<scope>provided</scope>
</dependency>
</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>2.2.3</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>
<enableVerbose>true</enableVerbose>
<relativeBaseDir>true</relativeBaseDir>
</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.5.0</version>
<executions>
</executions>
<configuration>
<appendAssemblyId>true</appendAssemblyId>
</configuration>
</plugin>
</plugins>
</build>
</project>
1 change: 1 addition & 0 deletions pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
</licenses>

<modules>
<module>ecocode-rules-specifications</module>
<module>python-plugin</module>
<module>java-plugin</module>
<module>javascript-plugin</module>
Expand Down

0 comments on commit c82dc7b

Please sign in to comment.