diff --git a/README.adoc b/README.adoc index c156d558b7..8a0d9b165a 100644 --- a/README.adoc +++ b/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[] diff --git a/ci/validate_asciidoc.sh b/ci/validate_asciidoc.sh index 3dbae32328..92e7473634 100755 --- a/ci/validate_asciidoc.sh +++ b/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 diff --git a/docs/description.adoc b/docs/description.adoc index 5c8e11408d..87fa7b1f1a 100644 --- a/docs/description.adoc +++ b/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 <>, <> 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. \ No newline at end of file diff --git a/rules/S5553/cfamily/rule.adoc b/rules/S5553/cfamily/rule.adoc index 95413bdd3c..d7b9c95b63 100644 --- a/rules/S5553/cfamily/rule.adoc +++ b/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 diff --git a/rules/S6655/cfamily/rule.adoc b/rules/S6655/cfamily/rule.adoc index 44fef3584e..bde819c8f2 100644 --- a/rules/S6655/cfamily/rule.adoc +++ b/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? diff --git a/shared_content/cfamily/dangling_reference_impact.adoc b/shared_content/cfamily/dangling_reference_impact.adoc new file mode 100644 index 0000000000..ad251faa6c --- /dev/null +++ b/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.