fix: report the searched directories when a linked resource is missing

Now that linked resources resolve against the .plain file's directory,
the syntax error lists the directories that were searched, in precedence
order, so the user can see where codeplain looked. The must-be-a-file
error reports the path it resolved to.

Author: Nejc Stebe

plain_file.py

@@ -101,10 +101,17 @@ def check_section_for_linked_resources(section, template_dirs):
 
         resolved_target = file_utils.resolve_linked_resource(template_dirs, link.node.target)
         if resolved_target is None:
-            raise PlainSyntaxError(f"Plain syntax error: Link {link.node.target} does not exist.")
+            searched_dirs = "\n".join(f"  {position}. {dir}" for position, dir in enumerate(template_dirs, start=1))
+            raise PlainSyntaxError(
+                f"Plain syntax error: Link {link.node.target} does not exist. "
+                f"Linked resources are looked up relative to the following directories "
+                f"(highest to lowest precedence):\n{searched_dirs}"
+            )
 
         if not os.path.isfile(resolved_target):
-            raise PlainSyntaxError(f"Plain syntax error: Link {link.node.target} must be a file.")
+            raise PlainSyntaxError(
+                f"Plain syntax error: Link {link.node.target} must be a file (resolved to {resolved_target})."
+            )
 
         if len(link.node.children) != 1:
             raise PlainSyntaxError(f"Plain syntax error: Link must have text specified (link: {link.node.target}).")

tests/data/plainfile/plain_source_with_missing_link.plain

@@ -0,0 +1,9 @@
+***definitions***
+
+***implementation reqs***
+
+- Implementation should be written in Python.
+
+***functional specs***
+
+- Links must point at an existing file [missing resource](resources/missing_resource.yaml).

tests/test_plainfileparser.py

@@ -146,6 +146,22 @@ def test_invalid_absolute_link(get_test_data_path):
         )
 
 
+def test_missing_link_error_lists_searched_directories(get_test_data_path):
+    """The error tells the user which directories were searched for the linked resource."""
+    plain_file_dir = get_test_data_path("data/plainfile")
+
+    with pytest.raises(PlainSyntaxError) as exception_info:
+        plain_file.plain_file_parser(
+            "plain_source_with_missing_link.plain",
+            [plain_file_dir],
+        )
+
+    message = str(exception_info.value)
+    assert "resources/missing_resource.yaml does not exist" in message
+    assert "highest to lowest precedence" in message
+    assert plain_file_dir in message
+
+
 def test_reference_link_parsing(get_test_data_path):
     _, plain_sections, _ = plain_file.plain_file_parser(
         "task_manager_with_reference_links.plain",