Forbid adding direct links to rules.sonarsource.com

rspec-tools/Pipfile

@@ -17,8 +17,8 @@ slackclient = "*"
 [dev-packages]
 pytest = ">=6.2.2"
 mypy = ">=0.800"
-rspec-tools = {file = ".", editable = true}
 pytest-snapshot = "*"
+rspec-tools = {file = ".", editable = true}
 
 [requires]
 python_version = "3.9"

rspec-tools/rspec_tools/validation/sanitize_asciidoc.py

@@ -4,7 +4,10 @@
 * "ifdef"/"endif" blocks should be well-formed for RSPEC
 * Inline code with backquotes is correctly escaped and balanced
 * Include commands are not appended to other code
+* "C++" is referred to using the {cpp} attribute
+* rules.sonarsource.com is not linked directly
 """
+
 import re
 from pathlib import Path
 
@@ -52,6 +55,8 @@
 
 CPP = re.compile(r"\b[Cc]\+\+")
 
+RULES_SONARSOURCE = re.compile(r"https?:\/\/rules\.sonarsource\.com\/(.*)\/RSPEC-\d+")
+
 # There is a regex trick here:
 # We want to skip passthrough macros, to not find pass:[``whatever``]
 # We do that by matching
@@ -199,7 +204,8 @@ def _advance_to_next_backquote(self, line: str, pos: int, line_number: int):
             cpp = CPP.search(line, pos)
         if cpp:
             self._on_error(
-                line_number, 'To avoid rendering issues, always use the "{cpp}" attribute to refer to the language C++'
+                line_number,
+                'To avoid rendering issues, always use the "{cpp}" attribute to refer to the language C++.',
             )
         return next_pos
 
@@ -211,7 +217,7 @@ def _process_description(self, line_number: int, line: str):
                 line_number - 1,
                 """An empty line is missing after the include.
 This may result in broken tags and other display issues.
-Make sure there are always empty lines before and after each include""",
+Make sure there are always empty lines before and after each include.""",
             )
         if INCLUDE.match(line):
             self._previous_line_was_include = True
@@ -220,11 +226,17 @@ def _process_description(self, line_number: int, line: str):
                     line_number,
                     """An empty line is missing before the include.
 This may result in broken tags and other display issues.
-Make sure there are always empty lines before and after each include""",
+Make sure there are always empty lines before and after each include.""",
                 )
             return
         else:
             self._previous_line_was_include = False
+        if RULES_SONARSOURCE.search(line) and not self._is_env_open:
+            self._on_error(
+                line_number,
+                """Do not put direct links to https://rules.sonarsource.com/.
+Just use the rule ID and let cross-reference substitution do its job.""",
+            )
         pos = 0
         res = self._advance_to_next_backquote(line, pos, line_number)
         # We filter out matches for passthrough. See comment near the BACKQUOTE declaration

rspec-tools/tests/resources/invalid-asciidoc/link_rule_sonarsource_com.adoc

@@ -0,0 +1,16 @@
+== Title
+
+In this case, there is also an impact on reliability and so it is handled by the rule https://rules.sonarsource.com/java/RSPEC-5810/[S5810].
+
+=== Documentation
+
+* https://rules.sonarsource.com/csharp/RSPEC-6420/[S6420 - Client instances should not be recreated on each Azure Function invocation]
+
+
+ifdef::env-github,rspecator-view[]
+
+https://rules.sonarsource.com/csharp/RSPEC-6420/[We ignore rspecator view]
+
+endif::env-github,rspecator-view[]
+
+http://rules.sonarsource.com/csharp/RSPEC-6420/[We detect http too]

rspec-tools/tests/resources/invalid-asciidoc/snapshots/include_stuck_after.txt

@@ -1,3 +1,3 @@
 $PATH/include_stuck_after.adoc:3 An empty line is missing after the include.
 This may result in broken tags and other display issues.
-Make sure there are always empty lines before and after each include
+Make sure there are always empty lines before and after each include.

rspec-tools/tests/resources/invalid-asciidoc/snapshots/include_stuck_before.txt

@@ -1,3 +1,3 @@
 $PATH/include_stuck_before.adoc:2 An empty line is missing before the include.
 This may result in broken tags and other display issues.
-Make sure there are always empty lines before and after each include
+Make sure there are always empty lines before and after each include.

rspec-tools/tests/resources/invalid-asciidoc/snapshots/link_rule_sonarsource_com.txt

@@ -0,0 +1,6 @@
+$PATH/link_rule_sonarsource_com.adoc:3 Do not put direct links to https://rules.sonarsource.com/.
+Just use the rule ID and let cross-reference substitution do its job.
+$PATH/link_rule_sonarsource_com.adoc:7 Do not put direct links to https://rules.sonarsource.com/.
+Just use the rule ID and let cross-reference substitution do its job.
+$PATH/link_rule_sonarsource_com.adoc:16 Do not put direct links to https://rules.sonarsource.com/.
+Just use the rule ID and let cross-reference substitution do its job.

rspec-tools/tests/resources/invalid-asciidoc/snapshots/two_stuck_includes.txt

@@ -1,6 +1,6 @@
 $PATH/two_stuck_includes.adoc:3 An empty line is missing after the include.
 This may result in broken tags and other display issues.
-Make sure there are always empty lines before and after each include
+Make sure there are always empty lines before and after each include.
 $PATH/two_stuck_includes.adoc:4 An empty line is missing before the include.
 This may result in broken tags and other display issues.
-Make sure there are always empty lines before and after each include
+Make sure there are always empty lines before and after each include.

rspec-tools/tests/resources/invalid-asciidoc/snapshots/unnamed_language.txt

@@ -1,2 +1,2 @@
-$PATH/unnamed_language.adoc:1 To avoid rendering issues, always use the "{cpp}" attribute to refer to the language C++
-$PATH/unnamed_language.adoc:3 To avoid rendering issues, always use the "{cpp}" attribute to refer to the language C++
+$PATH/unnamed_language.adoc:1 To avoid rendering issues, always use the "{cpp}" attribute to refer to the language C++.
+$PATH/unnamed_language.adoc:3 To avoid rendering issues, always use the "{cpp}" attribute to refer to the language C++.

rspec-tools/tests/validation/test_asciidoc_sanitization.py

@@ -29,6 +29,7 @@ def relative_output(capsys, path: Path):
         ("include_stuck_after", 1),
         ("two_stuck_includes", 2),
         ("unnamed_language", 2),
+        ("link_rule_sonarsource_com", 3),
     ],
 )
 def test_need_sanitation(

rules/S2583/comments-and-links.adoc

@@ -42,7 +42,7 @@ Last one should be already supported in fact.
 The message should be improved, as it is misleading. For example when the boolean expression is part of a chain of ``++OR++`` expressions, the subsequent code will be executed. Therefore _some subsequent code is never executed_ is misleading. (cc [~nicolas.harraudeau])
 
 
-Example for csharp (which came in https://github.com/SonarSource/sonar-dotnet/issues/2411[issue #2411]). Although this specific example is rather an occurence of https://rules.sonarsource.com/csharp/RSPEC-2589[RSPEC-2589] _Boolean expressions should not be gratuitous..._
+Example for csharp (which came in https://github.com/SonarSource/sonar-dotnet/issues/2411[issue #2411]). Although this specific example is rather an occurence of S2589 _Boolean expressions should not be gratuitous..._
 
 ----
     public void DoTest(Guid guid)