DOP-3211: ref label (#444)

* created new diagnostic error, implemented on ref nodes without children

* ensure correct args for ChildlessRef, added test

* edited ChildlessRef message

* re-editted message

Author: mmeigs

snooty/diagnostics.py

@@ -329,6 +329,23 @@ def __init__(
         self.candidates = candidates
 
 
+class ChildlessRef(Diagnostic):
+    severity = Diagnostic.Level.error
+
+    def __init__(
+        self,
+        target: str,
+        start: Union[int, Tuple[int, int]],
+        end: Union[None, int, Tuple[int, int]] = None,
+    ) -> None:
+        super().__init__(
+            f'Reference found without label: "{target}". Be sure to add label text to the :ref: itself OR place the target reference directly before a heading',
+            start,
+            end,
+        )
+        self.target = target
+
+
 class TodoInfo(Diagnostic):
     severity = Diagnostic.Level.info
 

snooty/postprocess.py

@@ -34,6 +34,7 @@
     AmbiguousTarget,
     CannotOpenFile,
     ChapterAlreadyExists,
+    ChildlessRef,
     Diagnostic,
     DuplicatedExternalToc,
     DuplicateDirective,
@@ -1393,6 +1394,12 @@ def enter_node(self, fileid_stack: FileIdStack, node: n.Node) -> None:
 
             injection_candidate.children = cloned_title_nodes
 
+            if not node.children:
+                line = node.span[0]
+                self.context.diagnostics[fileid_stack.current].append(
+                    ChildlessRef(node.target, line)
+                )
+
     def attempt_disambugation(
         self, fileid: FileId, candidates: Sequence[TargetDatabase.Result]
     ) -> Sequence[TargetDatabase.Result]:

snooty/test_postprocess.py

@@ -7,6 +7,7 @@
 from . import diagnostics
 from .diagnostics import (
     ChapterAlreadyExists,
+    ChildlessRef,
     DocUtilsParseError,
     DuplicatedExternalToc,
     DuplicateDirective,
@@ -1165,6 +1166,32 @@ def test_language_selector() -> None:
         ]
 
 
+def test_childless_ref_include() -> None:
+    with make_test(
+        {
+            Path(
+                "source/index.txt"
+            ): """
+.. _invisible-ref:
+
+.. include:: /includes/fact.rst
+""",
+            Path(
+                "source/includes/fact.rst"
+            ): """
+We have a link below here, but you can't see it!
+
+See that info at :ref:`invisible-ref`
+""",
+        }
+    ) as result:
+        assert {
+            k: [type(diag) for diag in v] for k, v in result.diagnostics.items() if v
+        } == {
+            FileId("includes/fact.rst"): [ChildlessRef]
+        }, "Childless Ref diagnostics error raised"
+
+
 def test_correct_diagnostic_path() -> None:
     with make_test(
         {