plain-parser 0.1.2.dev3__tar.gz → 0.1.2.dev4__tar.gz

{plain_parser-0.1.2.dev3 → plain_parser-0.1.2.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plain-parser
-Version: 0.1.2.dev3
+Version: 0.1.2.dev4
 Summary: Parser for ***plain specification files
 License-Expression: MIT
 License-File: LICENSE

{plain_parser-0.1.2.dev3 → plain_parser-0.1.2.dev4}/src/plain_parser/loaders.py

@@ -36,6 +36,20 @@ def open_from(dirs, file_name):
     return None
 
 
+def resolve_linked_resource(dirs, file_name):
+    """Return the first existing path for file_name across dirs, or None if not found.
+
+    Mirrors the search order used by open_from so that validating a linked resource and
+    loading it can never disagree.
+    """
+    for dir in dirs:
+        full_file_name = os.path.join(dir, file_name)
+        if os.path.exists(full_file_name):
+            return full_file_name
+
+    return None
+
+
 def load_linked_resources(template_dirs: list[str], resources_list, module_name: str):
     linked_resources = {}
 

{plain_parser-0.1.2.dev3 → plain_parser-0.1.2.dev4}/src/plain_parser/plain_file.py

@@ -88,7 +88,7 @@ def remove_quotes(token):
     token.children = tuple(new_children)
 
 
-def check_section_for_linked_resources(section):
+def check_section_for_linked_resources(section, template_dirs):
     linked_resources = []
     for link in traverse(section, klass=Link):
         parsed_url = urlparse(link.node.target)
@@ -97,11 +97,19 @@ def check_section_for_linked_resources(section):
                 f"Plain syntax error: Only relative links are allowed (text: {link.node.children[0].content}, target: {link.node.target})."
             )
 
-        if not os.path.exists(link.node.target):
-            raise PlainSyntaxError(f"Plain syntax error: Link {link.node.target} does not exist.")
+        resolved_target = loaders.resolve_linked_resource(template_dirs, link.node.target)
+        if resolved_target is None:
+            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(link.node.target):
-            raise PlainSyntaxError(f"Plain syntax error: Link {link.node.target} must be a file.")
+        if not os.path.isfile(resolved_target):
+            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}).")
@@ -120,15 +128,15 @@ def check_section_for_linked_resources(section):
         section.linked_resources = linked_resources
 
 
-def check_for_linked_resources(plain_source):
+def check_for_linked_resources(plain_source, template_dirs):
     for specification_heading in plain_spec.ALLOWED_SPECIFICATION_HEADINGS:
         if specification_heading in plain_source and hasattr(plain_source[specification_heading], "children"):
             for requirement in plain_source[specification_heading].children:
-                check_section_for_linked_resources(requirement)
+                check_section_for_linked_resources(requirement, template_dirs)
 
                 if hasattr(requirement, plain_spec.ACCEPTANCE_TESTS):
                     for acceptance_test in requirement.acceptance_tests:
-                        check_section_for_linked_resources(acceptance_test)
+                        check_section_for_linked_resources(acceptance_test, template_dirs)
 
 
 def process_section_code_variables(section, code_variables):
@@ -756,7 +764,7 @@ def process_required_modules(
                     )
 
         marshalled_plain_source = validate_and_marshall_module(
-            plain_file_parse_result, module_name, ancestor_exported_definitions, code_variables
+            plain_file_parse_result, module_name, ancestor_exported_definitions, code_variables, template_dirs
         )
         if module_name not in (chain_module_name for chain_module_name, _ in chain):
             chain.append((module_name, marshalled_plain_source))
@@ -793,6 +801,7 @@ def validate_and_marshall_module(
     module_name: str,
     exported_definitions: list[mistletoe.block_token.token],
     code_variables: dict,
+    template_dirs: list[str],
 ) -> dict:
     """Every check a module must pass after parsing, and its marshalled plain source tree."""
     if len(plain_file_parse_result.required_concepts) > 0:
@@ -826,7 +835,7 @@ def validate_and_marshall_module(
 
     process_acceptance_tests(plain_file_parse_result.plain_source)
 
-    check_for_linked_resources(plain_file_parse_result.plain_source)
+    check_for_linked_resources(plain_file_parse_result.plain_source, template_dirs)
 
     marshalled_plain_source = marshall_plain_source(plain_file_parse_result.plain_source)
 
@@ -881,7 +890,7 @@ def _parse_module(
     )
 
     marshalled_plain_source = validate_and_marshall_module(
-        plain_file_parse_result, module_name, exported_definitions, code_variables
+        plain_file_parse_result, module_name, exported_definitions, code_variables, template_dirs
     )
 
     return module_name, marshalled_plain_source, plain_file_parse_result.required_modules, chain

plain_parser-0.1.2.dev4/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).

{plain_parser-0.1.2.dev3 → plain_parser-0.1.2.dev4}/tests/data/plainfile/task_manager_with_reference_links.plain

@@ -29,9 +29,9 @@
 
 - Implement the entry point for :App:.
 
-- Show :TaskList:. The details of the user interface are provided in the file [task_list_ui_specification.yaml](tests/data/plainfile/task_list_ui_specification.yaml).
+- Show :TaskList:. The details of the user interface are provided in the file [task_list_ui_specification.yaml](task_list_ui_specification.yaml).
 
-- :User: should be able to add :Task:. Only valid :Task: items can be added. The details of the user interface are provided in the file [add_new_task_modal_specification.yaml](tests/data/plainfile/add_new_task_modal_specification.yaml).
+- :User: should be able to add :Task:. Only valid :Task: items can be added. The details of the user interface are provided in the file [add_new_task_modal_specification.yaml](add_new_task_modal_specification.yaml).
 
 - :User: should be able to delete :Task:.
 

{plain_parser-0.1.2.dev3 → plain_parser-0.1.2.dev4}/tests/test_cli.py

@@ -9,12 +9,12 @@ from plain_parser import cli
 
 
 @pytest.fixture
-def cli_data_dir(get_test_data_path):
+def cli_specs_dir(get_test_data_path):
     return get_test_data_path("data/cli")
 
 
-def test_check_valid_module_exits_zero(cli_data_dir, capsys):
-    exit_code = cli.main(["check", os.path.join(cli_data_dir, "valid.plain")])
+def test_check_valid_module_exits_zero(cli_specs_dir, capsys):
+    exit_code = cli.main(["check", os.path.join(cli_specs_dir, "valid.plain")])
 
     captured = capsys.readouterr()
     assert exit_code == 0
@@ -36,7 +36,7 @@ def test_without_subcommand_is_usage_error(capsys):
     assert exc_info.value.code == 2
 
 
-def test_console_script_is_installed_and_exits_zero(cli_data_dir):
+def test_console_script_is_installed_and_exits_zero(cli_specs_dir):
     # The venv's script dir may not be on PATH when pytest is run through an absolute interpreter path.
     search_path = os.pathsep.join([os.path.dirname(sys.executable), os.environ.get("PATH", "")])
     script = shutil.which("plain-parser", path=search_path)
@@ -46,7 +46,7 @@ def test_console_script_is_installed_and_exits_zero(cli_data_dir):
         pytest.fail(message) if os.environ.get("CI") else pytest.skip(message)
 
     result = subprocess.run(
-        [script, "check", os.path.join(cli_data_dir, "valid.plain")], capture_output=True, text=True
+        [script, "check", os.path.join(cli_specs_dir, "valid.plain")], capture_output=True, text=True
     )
 
     assert result.returncode == 0
@@ -66,32 +66,32 @@ def _assert_ok(result):
     assert out.endswith(": OK\n"), out
 
 
-def test_check_valid_module_in_subdirectory_from_parent(cli_data_dir, capsys, monkeypatch):
-    monkeypatch.chdir(cli_data_dir)
+def test_check_valid_module_in_subdirectory_from_parent(cli_specs_dir, capsys, monkeypatch):
+    monkeypatch.chdir(cli_specs_dir)
 
     exit_code, out, err = _run_check(capsys, os.path.join("subdir", "nested.plain"))
 
     _assert_ok((exit_code, out, err))
 
 
-def test_check_valid_module_with_linked_resource_in_acceptance_test(cli_data_dir, capsys, monkeypatch):
-    monkeypatch.chdir(cli_data_dir)
+def test_check_valid_module_with_linked_resource_in_acceptance_test(cli_specs_dir, capsys, monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
 
-    exit_code, out, err = _run_check(capsys, "acceptance_test_resource.plain")
+    exit_code, out, err = _run_check(capsys, os.path.join(cli_specs_dir, "acceptance_test_resource.plain"))
 
     _assert_ok((exit_code, out, err))
 
 
-def test_check_nonexistent_template_dir_is_ignored(cli_data_dir, capsys):
+def test_check_nonexistent_template_dir_is_ignored(cli_specs_dir, capsys):
     exit_code, out, err = _run_check(
-        capsys, os.path.join(cli_data_dir, "valid.plain"), "--template-dir", os.path.join(cli_data_dir, "nope")
+        capsys, os.path.join(cli_specs_dir, "valid.plain"), "--template-dir", os.path.join(cli_specs_dir, "nope")
     )
 
     _assert_ok((exit_code, out, err))
 
 
-def test_check_undefined_concept(cli_data_dir, capsys):
-    exit_code, out, err = _run_check(capsys, os.path.join(cli_data_dir, "undefined_concept.plain"))
+def test_check_undefined_concept(cli_specs_dir, capsys):
+    exit_code, out, err = _run_check(capsys, os.path.join(cli_specs_dir, "undefined_concept.plain"))
 
     assert exit_code == 1
     assert out == ""
@@ -101,30 +101,34 @@ def test_check_undefined_concept(cli_data_dir, capsys):
     assert "Traceback" not in err
 
 
-def test_check_missing_linked_resource(cli_data_dir, capsys, monkeypatch):
-    monkeypatch.chdir(cli_data_dir)
+def test_check_missing_linked_resource(cli_specs_dir, capsys, monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
 
-    exit_code, out, err = _run_check(capsys, "missing_resource.plain")
+    exit_code, out, err = _run_check(capsys, os.path.join(cli_specs_dir, "missing_resource.plain"))
 
     assert exit_code == 1
     assert out == ""
-    assert err == "Error: Plain syntax error: Link does_not_exist.md does not exist.\n"
+    assert err == (
+        "Error: Plain syntax error: Link does_not_exist.md does not exist. "
+        "Linked resources are looked up relative to the following directories (highest to lowest precedence):\n"
+        f"  1. {cli_specs_dir}\n"
+    )
 
 
-def test_check_binary_linked_resource(cli_data_dir, capsys, monkeypatch):
-    monkeypatch.chdir(cli_data_dir)
+def test_check_binary_linked_resource(cli_specs_dir, capsys, monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
 
-    exit_code, out, err = _run_check(capsys, "binary_resource.plain")
+    exit_code, out, err = _run_check(capsys, os.path.join(cli_specs_dir, "binary_resource.plain"))
 
     assert exit_code == 1
     assert out == ""
     assert err.startswith("Error: Referenced resource 'binary.bin' in module 'binary_resource' is a binary file.")
 
 
-def test_check_base64_blob_linked_resource(cli_data_dir, capsys, monkeypatch):
-    monkeypatch.chdir(cli_data_dir)
+def test_check_base64_blob_linked_resource(cli_specs_dir, capsys, monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
 
-    exit_code, out, err = _run_check(capsys, "base64_resource.plain")
+    exit_code, out, err = _run_check(capsys, os.path.join(cli_specs_dir, "base64_resource.plain"))
 
     assert exit_code == 1
     assert out == ""
@@ -134,10 +138,10 @@ def test_check_base64_blob_linked_resource(cli_data_dir, capsys, monkeypatch):
     )
 
 
-def test_check_invalid_linked_resource_in_required_module(cli_data_dir, capsys, monkeypatch):
-    monkeypatch.chdir(cli_data_dir)
+def test_check_invalid_linked_resource_in_required_module(cli_specs_dir, capsys, monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
 
-    exit_code, out, err = _run_check(capsys, "requires_binary_resource_top.plain")
+    exit_code, out, err = _run_check(capsys, os.path.join(cli_specs_dir, "requires_binary_resource_top.plain"))
 
     assert exit_code == 1
     assert out == ""
@@ -146,24 +150,24 @@ def test_check_invalid_linked_resource_in_required_module(cli_data_dir, capsys,
     )
 
 
-def test_check_code_variable_with_two_values(cli_data_dir, capsys):
-    exit_code, out, err = _run_check(capsys, os.path.join(cli_data_dir, "code_variable_conflict.plain"))
+def test_check_code_variable_with_two_values(cli_specs_dir, capsys):
+    exit_code, out, err = _run_check(capsys, os.path.join(cli_specs_dir, "code_variable_conflict.plain"))
 
     assert exit_code == 1
     assert out == ""
     assert err == "Error: Code variable variable_name has multiple values: first and second\n"
 
 
-def test_check_missing_plain_file(cli_data_dir, capsys):
-    exit_code, out, err = _run_check(capsys, os.path.join(cli_data_dir, "does_not_exist.plain"))
+def test_check_missing_plain_file(cli_specs_dir, capsys):
+    exit_code, out, err = _run_check(capsys, os.path.join(cli_specs_dir, "does_not_exist.plain"))
 
     assert exit_code == 1
     assert out == ""
     assert err == "Error: Module does not exist (does_not_exist).\n"
 
 
-def test_check_wrong_extension(cli_data_dir, capsys):
-    exit_code, out, err = _run_check(capsys, os.path.join(cli_data_dir, "not_plain.md"))
+def test_check_wrong_extension(cli_specs_dir, capsys):
+    exit_code, out, err = _run_check(capsys, os.path.join(cli_specs_dir, "not_plain.md"))
 
     assert exit_code == 1
     assert out == ""
@@ -189,10 +193,10 @@ def test_check_empty_template_dir_is_ignored(tmp_path, capsys, monkeypatch):
     assert err == "Error: Module does not exist (helper).\n"
 
 
-def test_check_binary_linked_resource_in_acceptance_test(cli_data_dir, capsys, monkeypatch):
-    monkeypatch.chdir(cli_data_dir)
+def test_check_binary_linked_resource_in_acceptance_test(cli_specs_dir, capsys, monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
 
-    exit_code, out, err = _run_check(capsys, "acceptance_test_binary_resource.plain")
+    exit_code, out, err = _run_check(capsys, os.path.join(cli_specs_dir, "acceptance_test_binary_resource.plain"))
 
     assert exit_code == 1
     assert out == ""
@@ -202,13 +206,13 @@ def test_check_binary_linked_resource_in_acceptance_test(cli_data_dir, capsys, m
 
 
 @pytest.mark.parametrize("interrupted_function", ["check", "resolve_config_file"])
-def test_check_interrupted_exits_130_without_traceback(cli_data_dir, capsys, monkeypatch, interrupted_function):
+def test_check_interrupted_exits_130_without_traceback(cli_specs_dir, capsys, monkeypatch, interrupted_function):
     def interrupt(*_):
         raise KeyboardInterrupt
 
     monkeypatch.setattr(cli, interrupted_function, interrupt)
 
-    exit_code = cli.main(["check", os.path.join(cli_data_dir, "valid.plain")])
+    exit_code = cli.main(["check", os.path.join(cli_specs_dir, "valid.plain")])
 
     captured = capsys.readouterr()
     assert exit_code == 130
@@ -317,8 +321,8 @@ def test_check_unreadable_config_is_usage_error(tmp_path, capsys):
     assert "Error reading config file" in capsys.readouterr().err
 
 
-def test_check_valid_module_prints_ok_line_with_file_as_given(cli_data_dir, capsys, monkeypatch):
-    monkeypatch.chdir(cli_data_dir)
+def test_check_valid_module_prints_ok_line_with_file_as_given(cli_specs_dir, capsys, monkeypatch):
+    monkeypatch.chdir(cli_specs_dir)
 
     exit_code, out, err = _run_check(capsys, "valid.plain")
 

{plain_parser-0.1.2.dev3 → plain_parser-0.1.2.dev4}/tests/test_loaders.py

@@ -4,7 +4,7 @@ import tempfile
 import pytest
 
 from plain_parser.exceptions import UnsupportedBase64Content, UnsupportedResourceType
-from plain_parser.loaders import MAX_BASE64_BLOB_LENGTH, load_linked_resources
+from plain_parser.loaders import MAX_BASE64_BLOB_LENGTH, load_linked_resources, resolve_linked_resource
 
 
 @pytest.fixture
@@ -96,3 +96,44 @@ def test_get_loaded_templates_missing_include_names_template(template_dir):
     message = str(exc_info.value)
     assert "nope.plain" in message
     assert "--template-dir" not in message
+
+
+def test_resolve_linked_resource_returns_none_when_missing(template_dir):
+    assert resolve_linked_resource([template_dir], "missing.md") is None
+
+
+def test_resolve_linked_resource_first_dir_wins():
+    with tempfile.TemporaryDirectory() as first, tempfile.TemporaryDirectory() as second:
+        for d in (first, second):
+            with open(os.path.join(d, "notes.md"), "w") as f:
+                f.write("x")
+
+        assert resolve_linked_resource([first, second], "notes.md") == os.path.join(first, "notes.md")
+
+
+def test_resolve_linked_resource_falls_back_to_later_dir():
+    with tempfile.TemporaryDirectory() as first, tempfile.TemporaryDirectory() as second:
+        with open(os.path.join(second, "notes.md"), "w") as f:
+            f.write("x")
+
+        assert resolve_linked_resource([first, second], "notes.md") == os.path.join(second, "notes.md")
+
+
+def test_resolve_linked_resource_parent_relative_path():
+    with tempfile.TemporaryDirectory() as root:
+        spec_dir = os.path.join(root, "plain")
+        os.mkdir(spec_dir)
+        with open(os.path.join(root, "shared.md"), "w") as f:
+            f.write("x")
+
+        assert resolve_linked_resource([spec_dir], "../shared.md") == os.path.join(spec_dir, "../shared.md")
+
+
+def test_resolve_linked_resource_directory_in_first_dir_shadows_file_in_second():
+    # Parity with codeplain: existence, not file-ness, decides the match.
+    with tempfile.TemporaryDirectory() as first, tempfile.TemporaryDirectory() as second:
+        os.mkdir(os.path.join(first, "notes.md"))
+        with open(os.path.join(second, "notes.md"), "w") as f:
+            f.write("x")
+
+        assert resolve_linked_resource([first, second], "notes.md") == os.path.join(first, "notes.md")

{plain_parser-0.1.2.dev3 → plain_parser-0.1.2.dev4}/tests/test_plainfileparser.py

@@ -144,14 +144,30 @@ 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",
         [get_test_data_path("data/plainfile")],
     )
     asserted_resources = [
-        "tests/data/plainfile/task_list_ui_specification.yaml",
-        "tests/data/plainfile/add_new_task_modal_specification.yaml",
+        "task_list_ui_specification.yaml",
+        "add_new_task_modal_specification.yaml",
     ]
     for functional_requirement in plain_sections[plain_spec.FUNCTIONAL_REQUIREMENTS]:
         if "linked_resources" not in functional_requirement:
@@ -178,13 +194,36 @@ def test_reference_link_parsing(get_test_data_path):
     assert plain_sections[plain_spec.FUNCTIONAL_REQUIREMENTS][1]["linked_resources"] == [
         {
             "text": "task_list_ui_specification.yaml",
-            "target": "tests/data/plainfile/task_list_ui_specification.yaml",
+            "target": "task_list_ui_specification.yaml",
+        }
+    ]
+    assert plain_sections[plain_spec.FUNCTIONAL_REQUIREMENTS][2]["linked_resources"] == [
+        {
+            "text": "add_new_task_modal_specification.yaml",
+            "target": "add_new_task_modal_specification.yaml",
+        }
+    ]
+
+
+def test_reference_link_parsing_independent_of_working_directory(get_test_data_path, monkeypatch, tmp_path):
+    """Linked resources resolve against the plain file's directory, not the invocation cwd."""
+    monkeypatch.chdir(tmp_path)
+
+    _, plain_sections, _ = plain_file.plain_file_parser(
+        "task_manager_with_reference_links.plain",
+        [get_test_data_path("data/plainfile")],
+    )
+
+    assert plain_sections[plain_spec.FUNCTIONAL_REQUIREMENTS][1]["linked_resources"] == [
+        {
+            "text": "task_list_ui_specification.yaml",
+            "target": "task_list_ui_specification.yaml",
         }
     ]
     assert plain_sections[plain_spec.FUNCTIONAL_REQUIREMENTS][2]["linked_resources"] == [
         {
             "text": "add_new_task_modal_specification.yaml",
-            "target": "tests/data/plainfile/add_new_task_modal_specification.yaml",
+            "target": "add_new_task_modal_specification.yaml",
         }
     ]