Create a shared_content folder at root

README.adoc

@@ -22,6 +22,7 @@ It is thanks to this file that you can add `tags`, `securityStandards` etc... to
 **** `rules/Sxxxx/common/resources`
 *** `rules/Sxxxx/[LANGUAGE]`: contains the language-specific RSPEC. For every rule, there must be at least one `[LANGUAGE]` subdirectory. +
 `[LANGUAGE]` can be any of the following:
+* https://github.com/SonarSource/rspec/tree/master/shared_content[shared_content] directory: contains content that needs to be shared among multiple rules. Subfolders are currently not standardized.
 
 include::supported_languages.adoc[]
 

ci/validate_asciidoc.sh

@@ -37,6 +37,8 @@ cd ..
 
 echo "Testing the following rules: ${affected_rules}"
 
+readonly ROOT=$PWD
+
 for dir in $affected_rules
 do
   if [ ! -d "$dir" ]; then
@@ -104,11 +106,17 @@ do
     # Files can be included through variables. We create a list of variables
     # These paths are relative to the file where they are _included_, not where they are _declared_
     # Which is why we need to create this list and cannot do anything with the paths it contains until we find the corresponding include
-    find "$dir" -name "*.adoc" -execdir sed -r -n -e 's/^:(\w+):\s+([A-Za-z0-9\/._-]+)$/\1\t\2/p' {} \; > vars
+    find "$dir" -name "*.adoc" ! -name 'tmp_*.adoc' -execdir sed -r -n -e 's/^:(\w+):\s+([A-Za-z0-9\/._-]+)$/\1\t\2/p' {} \; > vars
     # Directly included
-    find "$dir" -name "*.adoc" -execdir sh -c 'grep -Eh "include::" "$1" | grep -Ev "{\w+}" | grep -v "rule.adoc" | sed -r "s/include::(.*)\[\]/\1/" | xargs -r -I@ realpath "$PWD/@"' shell {} \; > included
+    find "$dir" -name "*.adoc" ! -name 'tmp_*.adoc' -execdir sh -c 'grep -h "include::" "$1" | grep -Ev "{\w+}" | grep -v "rule.adoc" | sed -r "s/include::(.*)\[\]/\1/" | xargs -r -I@ realpath "$PWD/@"' shell {} \; > included
     # Included through variable
-    VARS_FULL_PATH=$(realpath vars) PATH_WITH_VARIABLE=${PATH_WITH_VARIABLE} find "$dir" -name "*.adoc" -execdir sh -c 'grep -Eh "include::.*\{" "$1" | xargs -r -I@ $PATH_WITH_VARIABLE $VARS_FULL_PATH "@" | xargs -r -I@ realpath "$PWD/@"' shell {} \; >> included
+    VARS_FULL_PATH=$(realpath vars) PATH_WITH_VARIABLE=${PATH_WITH_VARIABLE} find "$dir" ! -name 'tmp_*.adoc' -name "*.adoc" -execdir sh -c 'grep -Eh "include::.*\{" "$1" | xargs -r -I@ $PATH_WITH_VARIABLE $VARS_FULL_PATH "@" | xargs -r -I@ realpath "$PWD/@"' shell {} \; >> included
+    # We should only include documents from the same rule or from shared_content
+    cross_references=$(grep -vEh "${ROOT}\/${dir}\/|${ROOT}\/shared_content\/" included)
+    if [[ -n "$cross_references" ]]; then
+        printf 'ERROR: Rule %s tries to include content from unallowed directory:\n%s\nTo share content between rules, you should use the "shared_content" folder at the root of the repository\n' "$dir" "$cross_references"
+        exit_code=1
+    fi
     find "$dir" -name "*.adoc" ! -name 'rule.adoc' ! -name 'tmp*.adoc' -exec sh -c 'realpath $1' shell {} \; > created
     orphans=$(comm -1 -3 <(sort -u included) <(sort -u created))
     if [[ -n "$orphans" ]]; then
@@ -137,6 +145,8 @@ else
   echo "No new asciidoc file changed"
 fi
 
+find rules -name "tmp*.adoc" -delete
+
 if (( exit_code == 0 )); then
     echo "Success"
 else

docs/description.adoc

@@ -1,5 +1,7 @@
 = Rule Description
 
+:toc:
+
 This document describes how `+rule.adoc+` and its dependencies should be structured.
 
 See also the <<styling_guide.adoc#,Styling Guidelines>>, <<tone_guide.adoc#,Tone Guide>> and https://docs.sonarqube.org/latest/extension-guide/adding-coding-rules/#coding-rule-guidelines[Coding rule guidelines].
@@ -321,3 +323,9 @@ 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).
+
+== Share content between rules
+
+You can share content between rules by using the `shared_content` folder at the root of the repository.
+
+Any included content for a rule can only come from the folder of the rule being described, `shared_content`, or any of their subfolders.

rules/S5553/cfamily/rule.adoc

@@ -42,16 +42,7 @@ If the definition of the temporary relies on another temporary,
 this second temporary will still be destroyed at the end of the full expression,
 creating an immediately dangling reference.
 
-=== What is the potential impact?
-
-Accessing a dangling reference or pointer causes undefined behavior.
-This means the compiler is not bound by the language standard anymore and your program has no meaning assigned to it.
-
-Practically this has a wide range of effects.
-In many cases, the access works by accident and succeeds at writing or reading a value.
-However, it can start misbehaving at any time.
-If compilation flags, compiler, platform, or runtime environment change,
-the same code can crash the application, corrupt memory, or leak a secret.
+include::../../../shared_content/cfamily/dangling_reference_impact.adoc[]
 
 == How to fix it
 

rules/S6655/cfamily/rule.adoc

@@ -49,18 +49,7 @@ void exampleWithFor() {
 }
 ----
 
-
-=== What is the potential impact?
-
-Accessing a dangling reference or pointer causes undefined behavior.
-This means the compiler is not bound by the language standard anymore
- and your program has no meaning assigned to it.
-
-Practically this has a wide range of effects.
-In many cases, the access works by accident and succeeds at writing or
-reading a value. However, it can start misbehaving at anytime.
-If compilation flags, compiler, platform, or runtime environment change,
-the same code can crash the application, corrupt memory, or leak a secret.
+include::../../../shared_content/cfamily/dangling_reference_impact.adoc[]
 
 === Why is the issue raised for reference variables?
 

shared_content/cfamily/dangling_reference_impact.adoc

@@ -0,0 +1,10 @@
+=== What is the potential impact?
+
+Accessing a dangling reference or pointer causes undefined behavior.
+This means the compiler is not bound by the language standard anymore and your program has no meaning assigned to it.
+
+Practically this has a wide range of effects.
+In many cases, the access works by accident and succeeds at writing or reading a value.
+However, it can start misbehaving at any time.
+If compilation flags, compiler, platform, or runtime environment change,
+the same code can crash the application, corrupt memory, or leak a secret.