Feat/allow relative imports in custom rule folder (#1150)

* Changed `unused-keyword` introduction version to 5.3.0

* Added workaround for allowing relative imports within custom rule folders

* Added test for relative imports in custom rules folder

* Simplified F string

* Added docs on how to import from a rules directory

* Renamed utilities.py to constants.py

* Fixed some more code blocks

* Even mode rule description code block fixes

Author: Lakitna

docs/external_rules.rst

@@ -170,6 +170,63 @@ Dotted syntax is also supported::
 ``rules`` dictionary should be available at the same level as checker that is using it. It could be either defined
 or imported from other files.
 
+Import from rules directory
+----------------------------
+
+Robocop rules can discovered from a directory. For example, using the following directory
+structure::
+
+    external_rules/
+    external_rules/some_rule.py
+    external_rules/constants.py
+    setup.py
+
+Inside ``some_rules.py``:
+
+..  code-block:: python
+    :caption: some_rules.py
+
+    from robocop.checkers import VisitorChecker
+    from robocop.rules import Rule, RuleSeverity
+    from external_rules.constants import DISALLOWED_KEYWORDS
+
+
+    rules = {
+        "9903": Rule(rule_id="9903", name="external-rule", msg="This is an external rule", severity=RuleSeverity.INFO)
+    }
+
+
+    class CustomRule(VisitorChecker):
+        """ Checker for missing keyword name. """
+        reports = ("external-rule",)
+
+        def visit_KeywordCall(self, node):  # noqa: N802
+            if node.keyword and node.keyword not in DISALLOWED_KEYWORDS:
+                self.report("external-rule", node=node)
+
+Inside ``constants.py``:
+
+..  code-block:: python
+    :caption: constants.py
+
+    DISALLOWED_KEYWORDS = ['Some Keyword', 'Another Keyword']
+
+Note how you can import other files from the directory:
+
+..  code-block:: python
+
+    from external_rules.constants import DISALLOWED_KEYWORDS
+
+You can also import relative to the external rules directory:
+
+..  code-block:: python
+
+    from constants import DISALLOWED_KEYWORDS
+
+You can import this rule directory using a relative path to the directory::
+
+    robocop --ext-rules ./external_rules .
+
 Rules disabled by default
 -------------------------
 

robocop/checkers/__init__.py

@@ -38,6 +38,7 @@
 import ast
 import importlib.util
 import inspect
+import sys
 from collections import defaultdict
 from importlib import import_module
 from pathlib import Path
@@ -202,6 +203,11 @@ def get_community_modules(self):
         return self.modules_from_paths([self.community_checkers_dir], recursive=True)
 
     def get_external_modules(self):
+        for ext_rule_path in self.external_rules_paths:
+            # Allow relative imports in external rules folder
+            sys.path.append(ext_rule_path)
+            sys.path.append(str(Path(ext_rule_path).parent))
+
         return self.modules_from_paths([*self.external_rules_paths], recursive=True)
 
     def _get_checkers_from_modules(self, modules, is_community):

robocop/checkers/community_rules/keywords.py

@@ -111,7 +111,7 @@ def comma_separated_list(value: str) -> set[str]:
         Example:
 
         Using a keyword with one embedded argument. Buying the drink and the size of the drink are
-        jumbled together.
+        jumbled together::
 
             *** Test Cases ***
             Prepare for an amazing movie
@@ -123,7 +123,7 @@ def comma_separated_list(value: str) -> set[str]:
 
         Change the embedded argument to a normal argument. Now buying the drink is separate from the
         size of the drink. In this approach, it's easier to see that you can change the size of your
-        drink.
+        drink::
 
             *** Test Cases ***
             Prepare for an amazing movie

robocop/checkers/community_rules/misc.py

@@ -16,7 +16,7 @@
         added_in_version="5.2.0",
         enabled=False,
         docs="""
-        Example of rule violation:
+        Example of rule violation::
 
             *** Settings ***
             Library    Collections
@@ -33,7 +33,7 @@
         added_in_version="5.2.0",
         enabled=False,
         docs="""
-        Example of rule violation:
+        Example of rule violation::
 
             *** Settings ***
             Resource   CustomResource.resource

tests/test_data/ext_rules/ext_rule_module_with_relative_import/bar.py

@@ -0,0 +1,2 @@
+# Import sibling file
+from foo import EXPECTED_KEYWORD

tests/test_data/ext_rules/ext_rule_module_with_relative_import/foo.py

@@ -0,0 +1,2 @@
+# Import inside rules folder
+from sub_dir.baz import EXPECTED_KEYWORD

tests/test_data/ext_rules/ext_rule_module_with_relative_import/single_rule.py

@@ -0,0 +1,23 @@
+from robocop.checkers import VisitorChecker
+from robocop.rules import Rule, RuleSeverity
+# Import starting with rules folder
+from ext_rule_module_with_relative_import.bar import EXPECTED_KEYWORD
+
+rules = {
+    "9905": Rule(
+        rule_id="9905",
+        name="external-rule",
+        msg="This is external rule with {{ parameter }} in msg",
+        severity=RuleSeverity.INFO,
+    )
+}
+
+
+class CustomRuleChecker(VisitorChecker):
+    """Checker for missing keyword name."""
+
+    reports = ("external-rule",)
+
+    def visit_KeywordCall(self, node):  # noqa: N802
+        if node.keyword and EXPECTED_KEYWORD not in node.keyword:
+            self.report("external-rule", node=node)

tests/test_data/ext_rules/ext_rule_module_with_relative_import/sub_dir/__init__.py

@@ -0,0 +1 @@
+EXPECTED_KEYWORD = 'Example'

tests/test_data/ext_rules/ext_rule_module_with_relative_import/sub_dir/baz.py

@@ -14,6 +14,7 @@
 EXT_MODULE = str(TEST_DATA / "ext_rule_module")
 EXT_MODULE_SIMPLE = str(TEST_DATA / "ext_rule_module_simple_import")
 EXT_MODULE_ROBOCOP_IMPORT = str(TEST_DATA / "ext_rule_module_import_robocop")
+EXT_MODULE_WITH_RELATIVE_IMPORT = str(TEST_DATA / "ext_rule_module_with_relative_import")
 
 
 @contextmanager
@@ -90,6 +91,13 @@ def test_loading_external_rule_from_dotted_module(self, robocop_pre_load):
             assert "9904" in robocop_pre_load.rules
             assert "9903" not in robocop_pre_load.rules
 
+    def test_loading_external_rule_including_relative_import(self, robocop_pre_load):
+        clear_imported_module("RobocopRules")
+        with add_sys_path(EXT_MODULE_WITH_RELATIVE_IMPORT):
+            robocop_pre_load.config.ext_rules = {EXT_MODULE_WITH_RELATIVE_IMPORT}
+            robocop_pre_load.load_checkers()
+            assert "9905" in robocop_pre_load.rules
+
     @pytest.mark.parametrize("config_dir", ["config_robocop", "config_pyproject"])
     def test_loading_external_rule_in_robocop_config(self, robocop_pre_load, config_dir):
         clear_imported_module("RobocopRules")