rspec/docs/description.adoc

= Rule Description

This document describes how `+rule.adoc+` and its dependencies should be structured.

See also the <<styling_guide.adoc#,Styling Guidelines>> and https://docs.sonarqube.org/latest/extension-guide/adding-coding-rules/#coding-rule-guidelines[Coding rule guidelines].

== Sections

There should be no first level titles (`+= Title+`) in your adoc.

The following are the only allowed second level titles for H2 for standard and hotspot rules
(for the education format, see the detailed <<3. Education Format,Education format>> section to see which headers are allowed):

include::./header_names/legacy_section_names.adoc[]

Most third-level and fourth-level titles (`+=== Title t3+` and `+==== Title t4+`) are not checked, the only type of rule description for which some of these
titles are checked are the education format rules (see below).

== Types of rule description

The above list of allowed H2 sections is an absolute list and covers all the different types of rule descriptions that exist.
However, depending on the type of rule description, the expected order and allowed sections are not the same.
There are currently 3 types of rule descriptions, each having a specific structure.

=== 1. Standard

The standard rule description is the currently most widespread format. It includes all _Code Smells_, _Bugs_ and most _Vulnerabilities_.

This is the "classical" format that starts with a description of the rule, and is usually followed by code examples of bad and good practices,
with some links to resources at the end.

This format has the structure of the following section:

. Description (no title)
. Noncompliant Code Example
. Compliant Solution
. Exceptions
. See
. See Also

Note that most sections are optional, only the description is mandatory.

=== 2. Hotspot

Specific to the _Hotspot_ issue type, this format is mostly similar to the standard one,
with the addition of 2 new sections: `Ask Yourself Whether` and `Recommended Secure Coding Practices`. Additionally, the `Noncompliant Code Example`
section has been renamed into `Sensitive Code Example`: this is based on the fact that for  _Hotspots_ there is no certainty that what was raised
is an actual vulnerability.

The possible sections for this format are the following:

. Description (no title)
. Ask Yourself Whether
. Recommended Secure Coding Practices
. Sensitive Code Example
. Compliant Solution
. Exceptions
. See
. See Also

=== 3. Education Format

Finally, the last format is the one related to the Progressive Education.
This new format has a completely different structure, with additional subsections and information,
to be as comprehensible as possible for the users.

This new structure is defined as follows:

* Short description (no title)

// This needs to be kept in sync with the [maps in the validation script](https://github.com/SonarSource/rspec/blob/master/rspec-tools/rspec_tools/validation/description.py#L33-L40).
* Why is this an issue?
** What is the potential impact?
* How to fix it
** Code examples
*** Noncompliant code example
*** Compliant solution
** How does this work?
** Pitfalls
** Going the extra mile
* How to fix it in {Framework Display Name}
** Code examples
*** Noncompliant code example
*** Compliant solution
** How does this work?
** Pitfalls
** Going the extra mile
* Resources (optional)
** Documentation
** Articles & blog posts
** Conference presentations
** Standards
** Benchmarks

Where the `How to fix it in {Framework Display Name}` section can be repeated multiple times when the rule description is defined per-framework.

The sections and subsections for this format are defined as follows:

* Short description (no title) [Optional]
+
A short introduction/summary of the topic, only a few sentences. +
Goal: The title (or message) of a rule might not always be clear due to its shortness, and this should make it clear to our users what the issue is about. Experienced developers will immediately understand what it is about, and developers not yet familiar with the issue at hand can dig deeper into the `Why is this an issue?` section.
+
* *Why is this an issue?* (level 2 title) [Mandatory]
+
Start at the basics and go into more depth to explain the concepts behind this type of issue. This is most likely the place where a lot of the content will be. +
Goal: Understand the concepts behind an issue.
+
* *What is the potential impact?* (level 3 title) [Optional]
+
What is the risk for me? What can go wrong?
This section can include multiple concrete threats as well.
https://github.com/SonarSource/rspec/blob/a51217c6d91abfa5e1d77d0ae0843e3903adf2d0/rules/S3649/impact.adoc[_Example._] +
Goal: Our users should understand the impact of this issue on their project.
+
* *How to fix it* or  *How to fix it in `{Framework Display Name}`* (level 2 title) [the title depends on whether the description is generic or framework-specifc. See examples below.]
+
This section consists of one or multiple fixes for this type of issue (`Noncompliant code example` vs. `Compliant solution`). There can be multiple fixes for different libraries and/or frameworks. +
Goal: Get an idea of how this issue can be fixed for my project/framework, why this works, what to look out for, and also how to continue improving on this topic.
+
* *How does this work?* (level 3 title) [Optional]
+
Explain why this fixes the problem.
+
* *Pitfalls* (level 3 title) [Optional]
+
One or multiple pitfalls to take into account when working on fixing this issue.
https://github.com/SonarSource/rspec/blob/a51217c6d91abfa5e1d77d0ae0843e3903adf2d0/rules/S6096/common/pitfalls/partial-path-traversal.adoc[_Example._]
+
* *Going the extra mile* (level 3 title) [Optional]
+
Even though the issue might be fixed, most of the time there can be way/s to further improve on this issue or to harden your project.
The subsection should be concise.
https://github.com/SonarSource/rspec/blob/a51217c6d91abfa5e1d77d0ae0843e3903adf2d0/rules/S5131/common/extra-mile/csp.adoc[_Example._]
+
* *Resources* (level 2 title) [Optional]
+
Include resources if our users want to dig even deeper, that can be presented in the different categories.
https://github.com/SonarSource/rspec/tree/a51217c6d91abfa5e1d77d0ae0843e3903adf2d0/rules/S5131/common/resources[_Example._] +
Goal: Allow the user to dig deeper by providing a curated list of resources.
+
* *Documentation* (level 3 title) [Optional]
* *Articles & blog posts* (level 3 title) [Optional]
* *Conference presentations* (level 3 title) [Optional]
* *Standards* (level 3 title) [Optional]
* *Benchmarks* (level 3 title) [Optional]

Note that most sections and subsections are optional, only the `Why is this an issue?` and `How to fix it`/ `How to fix it in {Framework Display Name}` main
sections are mandatory.

Content of the section "_How to fix it_ / _How to fix it in {Framework Display Name}_" can either be generic or framework specific.

When the content is generic, the "_How to fix it_" title must be used, and the section should only appear once. Example:
....
== Why is this an issue?
Explanation of why this is bad.

== How to fix it

=== Code examples

==== Noncompliant code example
[source,js,diff-id=1,diff-type=noncompliant]
----
var myExample;
----

==== Compliant solution
[source,js,diff-id=1,diff-type=compliant]
----
var myExample = 0;
----

=== How does this work?
We added something.

== Resources
=== Documentation
http-address-of-documentation[My doc name]

....
Note that you can see two special attributes (`diff-id` and `diff-type`) used in the code examples above, these attributes are explained in the <<Diff view,Diff view>>
section below.

When the content is framework-specific, one or more "_How to fix it in `{Framework Display Name}`_" sections (with their respective subsections) must be present.
Each repetition will represent the specific _How to fix it_ section of a given framework.
For example:
....
== How to fix it in Spring

=== Code examples
... Some generic text and code examples for Spring...

=== How does this work?
... Explanation about how the exploit works in Spring...

=== Pitfalls
... Generic and Spring-specific pitfalls to avoid when fixing the issue...

== How to fix it in JSP

=== Code examples
... Some generic text and code examples for JSP...

=== How does this work?
... Explanation about how the exploit works in JSP...

=== Pitfalls
... Generic and JSP-specific pitfalls to avoid when fixing the issue...
....

Ideally, by convention and for maintainability, each framework _How to fix it_ section will be defined in separate files.
Ex:
....
 == Why is this an issue?
 ... Explanation ...

 # How to fix it sections

 include::./how-to-fix-it/framework-1.adoc[]

 include::./how-to-fix-it/framework-2.adoc[]

 == Resources
 === Documentation
 http-address-of-documentation[My doc name]
....

Note that each framework-specific _How to fix it_ subsection must start with an H2 title following the given format:
`== How to fix it in [an|a|the]? {Framework name}`.
This is important, as this format will be expected by the analyzers when loading the rule content to recognize the different subsections.
Furthermore, the display name of the framework has to match an allowed framework
display name, as defined in <<header_names/allowed_framework_names.adoc#,this allowed framework names file>>.

== Code Examples

Whenever possible, prefix your code blocks with `[source,language]`, in order to get syntax coloring.

....
[source,cpp]
----
int main(int argc, const char** argv) {
    return 0;
}
----
....

That is mandatory for the Noncompliant and Compliant code example sections, just recommended - at the moment - for other sections.

The language names accepted are usually the name we already use for the language folders in RSPEC. Exceptions are:

cfamily:: use `cpp`, `c`, or `objectivec`

plsql:: use `sql`

tsql:: use `sql`

In case no language is appropriate for a code block (for example shared examples between multiple languages), you can use `text` as the language.

=== Diff view

Additionally, you can also use two attributes to let the products know your code examples should be highlighted with a diff view when possible
(showing the changes in the code examples as red/green).
These attributes are optional and if a product does not yet support the diff view feature, these attributes will simply be ignored.

These attributes are `diff-id=X` and `diff-type=[noncompliant|compliant]`. The `diff-id` attributes describe which code examples should
be compared together, and the `diff-type` attribute explain how it should be displayed `Noncompliant` (red) vs. `Compliant` (green).
A single and unique diff-id should be used only once for each type of code example as shown in the description of a rule.
....
==== Noncompliant code example
[source,js,diff-id=1,diff-type=noncompliant]
----
var myExample;
----

==== Compliant solution
[source,js,diff-id=1,diff-type=compliant]
----
var myExample = 0;
----
....


== Parameters

Parameters should be listed in a subsection as follow:

....
=== Parameters

.name
****
_TYPE_

----
default value
----

Description of what the parameter does.
****

.name2
****
----
another default value
----
Description of what this second parameter does.
****

.name3
****
_TYPE_

Description of what this third parameter does.
****

.name4
****
Description of what this fourth parameter does.
****

....

The parameter name and the description are mandatory. The type and default value are not.

The parameter name with a `.` before will be the title of the block below marked by `****`.

We always use `----` around the default parameter to avoid having a special character confuse AsciiDoctor and to create a visual consistency for all parameters.

== Comment a rule

Comments and links that were created on Jira have been gathered in a `comments-and-links.adoc` file for each concerned rule. +
You can add a comment anywhere in a rule by adding the following lines in the `*.adoc` file:
[source]
----
\ifdef::env-github,rspecator-view[]
John Doe (9 Jun 2021, 15:49): my comment on the rule
\endif::env-github,rspecator-view[]
----
This way, your comment will only be visible in GitHub preview and on the Search Page (and will not be visible for the user).