scripts: tighten ref directive check

Author: khancyr

scripts/check_ref_directives.py

@@ -4,8 +4,9 @@
 Two rules are enforced:
   1. No alphanumeric/underscore/colon character directly before ``:ref:``
      (missing space before the role).
-  2. No space between a closing :ref: backtick and a punctuation character
-     ``.``, ``,`` or ``:``  (trailing space before punctuation).
+  2. No whitespace between ``:ref:`` and its opening backtick.
+  3. No space between a closing ``:ref:`` backtick and a punctuation character
+     ``.``, ``,`` or ``:``.  (trailing space before punctuation).
 
 """
 
@@ -15,7 +16,8 @@
 import sys
 
 CHARACTER_BEFORE_RE = re.compile(r"[a-zA-Z0-9_:]:ref:")
-CHARACTER_AFTER_RE = re.compile(r"(:ref:`.*?`[_]{0,2}) ([\.,:])")
+CHARACTER_AFTER_RE = re.compile(r":ref:[^`]")
+SPACE_BEFORE_PUNCT_RE = re.compile(r"(:ref:`.*?`[_]{0,2}) ([\.,:])")
 
 
 def check_file(path: pathlib.Path) -> list[str]:
@@ -31,7 +33,11 @@ def check_file(path: pathlib.Path) -> list[str]:
             )
         if CHARACTER_AFTER_RE.search(line):
             errors.append(
-                f'{path}:{i}: remove space between :ref: and following punctuation'
+                f'{path}:{i}: remove whitespace between :ref: and its opening backtick'
+            )
+        if SPACE_BEFORE_PUNCT_RE.search(line):
+            errors.append(
+                f'{path}:{i}: remove space between :ref: closing backtick and punctuation'
             )
     return errors
 

scripts/tests/__init__.py

@@ -9,6 +9,8 @@
 
 sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
 
+import check_ref_directives  # noqa: E402
+import check_rst_literal_blocks  # noqa: E402
 import check_youtube_timestamps  # noqa: E402
 
 
@@ -119,5 +121,135 @@ def test_unicode_error(self):
         self.assertIn("UnicodeDecodeError", errors[0])
 
 
+class TestCheckRefDirectives(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.tmp = pathlib.Path(self._tmp.name)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_valid_ref(self):
+        path = _rst(self.tmp, "valid.rst", "See :ref:`some-label` for details.\n")
+        self.assertEqual(check_ref_directives.check_file(path), [])
+
+    def test_char_before_ref(self):
+        path = _rst(self.tmp, "before.rst", "Seex:ref:`some-label` for details.\n")
+        errors = check_ref_directives.check_file(path)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("remove character directly before", errors[0])
+
+    def test_special_char_before_ref_not_caught(self):
+        path = _rst(self.tmp, "ampersand.rst", "See (:ref:`some-label`) for details.\n")
+        self.assertEqual(check_ref_directives.check_file(path), [])
+
+    def test_space_before_ref_is_valid(self):
+        path = _rst(self.tmp, "space_before.rst", "See :ref:`some-label` for details.\n")
+        self.assertEqual(check_ref_directives.check_file(path), [])
+
+    def test_space_after_ref(self):
+        path = _rst(self.tmp, "after.rst", "See :ref: `some-label` for details.\n")
+        errors = check_ref_directives.check_file(path)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("remove whitespace", errors[0])
+
+    def test_char_after_ref(self):
+        path = _rst(self.tmp, "char_after.rst", "See :ref:x`some-label` for details.\n")
+        errors = check_ref_directives.check_file(path)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("remove whitespace", errors[0])
+
+    def test_space_before_period(self):
+        path = _rst(self.tmp, "punct_period.rst", "See :ref:`some-label` .\n")
+        errors = check_ref_directives.check_file(path)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("remove space between", errors[0])
+
+    def test_space_before_comma(self):
+        path = _rst(self.tmp, "punct_comma.rst", "See :ref:`some-label` , and more.\n")
+        errors = check_ref_directives.check_file(path)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("remove space between", errors[0])
+
+    def test_space_before_colon(self):
+        path = _rst(self.tmp, "punct_colon.rst", "See :ref:`some-label` : details.\n")
+        errors = check_ref_directives.check_file(path)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("remove space between", errors[0])
+
+    def test_no_space_before_period_valid(self):
+        path = _rst(self.tmp, "valid_punct.rst", "See :ref:`some-label`.\n")
+        self.assertEqual(check_ref_directives.check_file(path), [])
+
+    def test_unicode_error(self):
+        path = self.tmp / "bad.rst"
+        path.write_bytes(b"See :ref:`label` \xff.\n")
+        errors = check_ref_directives.check_file(path)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("UnicodeDecodeError", errors[0])
+
+    def test_main_valid(self):
+        path = _rst(self.tmp, "valid.rst", "See :ref:`some-label` for details.\n")
+        with patch("sys.argv", ["check_ref_directives", str(path)]):
+            self.assertEqual(check_ref_directives.main(), 0)
+
+    def test_main_invalid(self):
+        path = _rst(self.tmp, "invalid.rst", "Seex:ref:`some-label` for details.\n")
+        with patch("sys.argv", ["check_ref_directives", str(path)]):
+            self.assertEqual(check_ref_directives.main(), 1)
+
+    def test_non_rst_skipped(self):
+        path = self.tmp / "errors.txt"
+        path.write_text("See&:ref:`some-label` for details.\n", encoding="utf-8")
+        with patch("sys.argv", ["check_ref_directives", str(path)]):
+            self.assertEqual(check_ref_directives.main(), 0)
+
+
+class TestCheckRstLiteralBlocks(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.tmp = pathlib.Path(self._tmp.name)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_valid_literal_block(self):
+        path = _rst(self.tmp, "valid.rst", "Some text.\n\n::\n\n    code here\n")
+        self.assertEqual(check_rst_literal_blocks.check_file(path), [])
+
+    def test_missing_blank_before(self):
+        path = _rst(self.tmp, "before.rst", "Some text.\n::\n\n    code here\n")
+        errors = check_rst_literal_blocks.check_file(path)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("blank line before", errors[0])
+
+    def test_missing_blank_after(self):
+        path = _rst(self.tmp, "after.rst", "Some text.\n\n::\n    code here\n")
+        errors = check_rst_literal_blocks.check_file(path)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("blank line after", errors[0])
+
+    def test_missing_blank_both(self):
+        path = _rst(self.tmp, "both.rst", "Some text.\n::\n    code here\n")
+        errors = check_rst_literal_blocks.check_file(path)
+        self.assertEqual(len(errors), 2)
+
+    def test_main_valid(self):
+        path = _rst(self.tmp, "valid.rst", "Some text.\n\n::\n\n    code here\n")
+        with patch("sys.argv", ["check_rst_literal_blocks", str(path)]):
+            self.assertEqual(check_rst_literal_blocks.main(), 0)
+
+    def test_main_invalid(self):
+        path = _rst(self.tmp, "invalid.rst", "Some text.\n::\n\n    code here\n")
+        with patch("sys.argv", ["check_rst_literal_blocks", str(path)]):
+            self.assertEqual(check_rst_literal_blocks.main(), 1)
+
+    def test_non_rst_skipped(self):
+        path = self.tmp / "errors.txt"
+        path.write_text("Some text.\n::\n    code here\n", encoding="utf-8")
+        with patch("sys.argv", ["check_rst_literal_blocks", str(path)]):
+            self.assertEqual(check_rst_literal_blocks.main(), 0)
+
+
 if __name__ == "__main__":
     unittest.main()