SONARSEC-3040 Update checks and documentation to fit new rule format (#1004)

README.adoc

@@ -15,6 +15,11 @@ It also contains rules which have been dropped and rules which will one day be i
 *** `rules/Sxxxx/*.adoc`: Asciidoc files which can be reused by multiple language-specific descriptions.
 *** `rules/Sxxxx/metadata.json`: rule metadata shared between language-specific RSPECs. Each language can override fields in its own `metadata.json` file. +
 It is thanks to this file that you can add `tags`, `securityStandards` etc... to your rule.
+*** `rules/Sxxxx/common`: contains common content shared by all the supported languages. It is organized in the following subdirectories:
+**** `rules/Sxxxx/common/fix`
+**** `rules/Sxxxx/common/images`
+**** `rules/Sxxxx/common/pitfalls`
+**** `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:
 include::supported_languages.adoc[]

ci/validate_asciidoc.sh

@@ -1,6 +1,8 @@
 #!/bin/bash
 set -uo pipefail
 
+readonly ALLOWED_RULE_SUB_FOLDERS=['common'];
+
 # Install script dependencies
 cd rspec-tools
 pipenv install
@@ -60,20 +62,23 @@ do
     do
       language=${language%*/}
       if [[ ! "${supportedLanguages[*]}" == *"${language##*/}"* ]]; then
-        echo "ERROR: ${language##*/} is not a supported language"
-        exit_code=1
-      fi
-      RULE="$language/rule.adoc"
-      if test -f "$RULE"; then
-        # We build this filename that describes the path to workaround the fact that asciidoctor will not tell
-        # us the path of the file in case of error.
-        # We can remove it if https://github.com/asciidoctor/asciidoctor/issues/3414 is fixed.
-        TMP_ADOC="$language/tmp_$(basename "${dir}")_${language##*/}.adoc"
-        echo "== Description" > "$TMP_ADOC"
-        cat "$RULE" >> "$TMP_ADOC"
+        if [[ ! "${ALLOWED_RULE_SUB_FOLDERS[*]}" == *"${language##*/}"* ]]; then
+          echo "ERROR: ${language##*/} is not a supported language"
+          exit_code=1
+        fi
       else
-        echo "ERROR: no asciidoc file $RULE"
-        exit_code=1
+        RULE="$language/rule.adoc"
+        if test -f "$RULE"; then
+          # We build this filename that describes the path to workaround the fact that asciidoctor will not tell
+          # us the path of the file in case of error.
+          # We can remove it if https://github.com/asciidoctor/asciidoctor/issues/3414 is fixed.
+          TMP_ADOC="$language/tmp_$(basename "${dir}")_${language##*/}.adoc"
+          echo "== Description" > "$TMP_ADOC"
+          cat "$RULE" >> "$TMP_ADOC"
+        else
+          echo "ERROR: no asciidoc file $RULE"
+          exit_code=1
+        fi
       fi
     done
 

docs/section_names.adoc

@@ -7,3 +7,6 @@
 * Ask Yourself Whether
 * Recommended Secure Coding Practices
 * Deprecated
+* Why is this an issue?
+* How to fix it?
+* Resources

rspec-tools/rspec_tools/rules.py

@@ -4,6 +4,7 @@ from pathlib import Path
 from typing import Final, Generator, Iterable, Optional
 from bs4 import BeautifulSoup
 from rspec_tools.errors import RuleNotFoundError
+from rspec_tools.utils import load_valid_languages
 
 
 METADATA_FILE_NAME: Final[str] = 'metadata.json'
@@ -76,7 +77,8 @@ class GenericRule:
 
   @property
   def specializations(self) -> Generator[LanguageSpecificRule, None, None]:
-    return (LanguageSpecificRule(child, self) for child in self.rule_path.iterdir() if child.is_dir())
+    return (LanguageSpecificRule(child, self) for child in self.rule_path.iterdir() if
+            child.is_dir() and child.name in load_valid_languages())
   
   def get_language(self, language: str) -> LanguageSpecificRule:
     return LanguageSpecificRule(self.rule_path.joinpath(language), self)

rspec-tools/tests/resources/rules/S120/common/common.adoc

@@ -0,0 +1 @@
+Common content

rspec-tools/tests/test_rules_repository.py

@@ -1,5 +1,5 @@
 from pathlib import Path
-
+import os
 import pytest
 from rspec_tools.rules import RulesRepository
 from rspec_tools.errors import RuleNotFoundError
@@ -13,9 +13,14 @@ def test_list_rules(mockrules: Path):
 def test_list_languages(mockrules: Path):
   '''Check that languages are all listed.'''
   rule = RulesRepository(rules_path=mockrules).get_rule('S120')
+
   languages = {lang.language for lang in rule.specializations}
   assert languages == {'flex', 'java', 'plsql'}
 
+  rulePath = os.path.join(mockrules, 'S120')
+  ruleSubDirs = [subDir for subDir in os.listdir(rulePath) if os.path.isdir(os.path.join(rulePath, subDir))]
+  assert sorted(ruleSubDirs) == ['common', 'flex', 'java', 'plsql']
+
 
 def test_get_metadata(mockrules: Path):
   '''Check that language metadata are correctly overriden.'''