DOP-3064: Validate relative URLs in card directives (#408)

* some initial work to add validation in the correct code path

* pull path logic into util function

* simple test for relative url util

* make linter happy

* leverage existing function, add parser-level testing

* use existing add_doc_target_ext function

* enforce invariant for structure of relative paths

* make linter happy

* remove unnecessary string cast

* add test for malformed relative path

* compile regex at global scope to avoid repeated compilation/unnecessary reliance on cache

Author: drew-beckmen

snooty/diagnostics.py

@@ -506,6 +506,19 @@ def did_you_mean(self) -> List[str]:
         return [f"`{self.parts[0]} <{self.parts[1]}>`__"]
 
 
+class MalformedRelativePath(Diagnostic):
+    severity = Diagnostic.Level.error
+
+    def __init__(
+        self,
+        relative_path: str,
+        start: Union[int, Tuple[int, int]],
+        end: Union[None, int, Tuple[int, int]] = None,
+    ) -> None:
+        super().__init__(f"Malformed relative path {relative_path}", start, end)
+        self.relative_path = relative_path
+
+
 class MissingTab(Diagnostic):
     severity = Diagnostic.Level.error
 

snooty/parser.py

@@ -55,6 +55,7 @@
     InvalidTableStructure,
     InvalidURL,
     MalformedGlossary,
+    MalformedRelativePath,
     MissingChild,
     RemovedLiteralBlockSyntax,
     TabMustBeDirective,
@@ -73,6 +74,7 @@
 from .util import RST_EXTENSIONS
 
 NO_CHILDREN = (n.SubstitutionReference,)
+MULTIPLE_FORWARD_SLASHES = re.compile(r"([\/])\1")
 logger = logging.getLogger(__name__)
 
 
@@ -923,9 +925,12 @@ def _locate_text(text: str) -> int:
 
         elif key in {"mongodb:card"}:
             image_argument = options.get("icon")
+            url_argument = options.get("url")
 
             if image_argument:
                 self.validate_and_add_asset(doc, image_argument, line)
+            if url_argument and not url_argument.startswith("http"):
+                self.validate_relative_url(url_argument, line)
 
         return doc
 
@@ -940,6 +945,21 @@ def validate_and_add_asset(
                 CannotOpenFile(Path(image_argument), err.strerror, line)
             )
 
+    def validate_relative_url(self, url_argument: str, line: int) -> None:
+        """Validate relative URL points to page within current docs site.
+        URLs can be of the form /foo, foo, /foo/"""
+        target_path = util.add_doc_target_ext(
+            url_argument, self.docpath, self.project_config.source_path
+        )
+
+        if not target_path.is_file():
+            err_message = (
+                f"{os.strerror(errno.ENOENT)} for relative path {url_argument}"
+            )
+            self.diagnostics.append(CannotOpenFile(target_path, err_message, line))
+        elif MULTIPLE_FORWARD_SLASHES.search(url_argument) is not None:
+            self.diagnostics.append(MalformedRelativePath(url_argument, line))
+
     def validate_doc_role(self, node: docutils.nodes.Node) -> None:
         """Validate target for doc role"""
         resolved_target_path = util.add_doc_target_ext(

snooty/test_parser.py

@@ -15,6 +15,7 @@
     InvalidURL,
     MakeCorrectionMixin,
     MalformedGlossary,
+    MalformedRelativePath,
     TabMustBeDirective,
     UnexpectedIndentation,
     UnknownTabID,
@@ -119,6 +120,48 @@ def test_chapter() -> None:
     assert isinstance(diagnostics[0], CannotOpenFile)
 
 
+def test_card() -> None:
+    """Test card directive"""
+    path = ROOT_PATH.joinpath(Path("test.rst"))
+    project_config = ProjectConfig(ROOT_PATH, "", source="./")
+    parser = rstparser.Parser(project_config, JSONVisitor)
+
+    SOURCE_DIR = "/test_project/source/"
+    VALID_URLS = ["index", "index/"]
+    INVALID_URL = [("foo", CannotOpenFile), ("index//", MalformedRelativePath)]
+    CARD_CONTENT = """
+.. card-group::
+   :columns: 3
+   :layout: carousel
+
+   .. card::
+      :headline: Develop Applications
+      :cta: Test Develop Applications Relative URL Test
+      :url: %s
+
+      This card was built with a relative URL.
+"""
+
+    for url in VALID_URLS:
+        page, diagnostics = parse_rst(
+            parser,
+            path,
+            CARD_CONTENT % (SOURCE_DIR + url),
+        )
+
+        page.finish(diagnostics)
+        assert len(diagnostics) == 0
+
+    for url, error_type in INVALID_URL:
+        page, diagnostics = parse_rst(
+            parser,
+            path,
+            CARD_CONTENT % (SOURCE_DIR + url),
+        )
+        assert len(diagnostics) == 1
+        assert isinstance(diagnostics[0], error_type)
+
+
 def test_tabs() -> None:
     tabs_path = ROOT_PATH.joinpath(Path("test_tabs.rst"))
     project_config = ProjectConfig(ROOT_PATH, "", source="./")

snooty/util.py

@@ -169,7 +169,7 @@ def add_doc_target_ext(target: str, docpath: PurePath, project_root: Path) -> Pa
     new_suffix = target_path.suffix + ".txt"
     target_path = target_path.with_suffix(new_suffix)
 
-    fileid, resolved_target_path = reroot_path(target_path, docpath, project_root)
+    _, resolved_target_path = reroot_path(target_path, docpath, project_root)
     return resolved_target_path