Separate parse-time vs usage errors; reclassify import check

Split the misnamed check_if_functional_requirements_are_specified (which
mutated a caller-passed buffer, raised a validation error, and returned
header presence) into three single-purpose helpers:

- has_functional_specs_section: pure presence predicate
- count_functionalities: functionality count
- validate_functionalities_have_implementation_reqs: the impl-reqs validation

Reclassify 'imported module must not contain functionalities' from a
PlainSyntaxError to the new usage error ImportedModuleWithFunctionalitiesError.
The file is syntactically valid and would be fine as a render target; it is
only wrong for the import role, so it is a usage error, not a syntax error.
This also fixes the prior mislabeling where such a module could surface the
misleading 'no implementation reqs' syntax error first.

Behavior preserved: missing functional specs (usage), empty functional specs
section (syntax), and functionalities-without-impl-reqs (syntax) are unchanged.

Author: pedjaradenkovic

plain2code.py

@@ -25,6 +25,7 @@
 from plain2code_exceptions import (
     ConflictingRequirements,
     GitNotInstalledError,
+    ImportedModuleWithFunctionalitiesError,
     InvalidAPIKey,
     InvalidFridArgument,
     MissingAPIKey,
@@ -66,6 +67,7 @@
     MissingResource,
     TemplateNotFoundError,
     PlainSyntaxError,
+    ImportedModuleWithFunctionalitiesError,
     MissingFunctionalitiesError,
     MissingPreviousFunctionalitiesError,
     MissingAPIKey,

plain2code_exceptions.py

@@ -84,6 +84,17 @@ class MissingFunctionalitiesError(Exception):
     pass
 
 
+class ImportedModuleWithFunctionalitiesError(Exception):
+    """Raised when a module brought in via ``import`` contains functional specs.
+
+    This is a usage error, not a syntax error: the module is syntactically valid
+    and would be fine as a render target, but functionalities are not allowed in
+    the import role.
+    """
+
+    pass
+
+
 class NetworkConnectionError(Exception):
     """Raised when there is a network connectivity issue with the API server."""
 

plain_file.py

@@ -18,6 +18,7 @@
 import file_utils
 import plain_spec
 from plain2code_exceptions import (
+    ImportedModuleWithFunctionalitiesError,
     MissingFunctionalitiesError,
     ModuleDoesNotExistError,
     PlainSyntaxError,
@@ -156,17 +157,27 @@ def process_code_variables(plain_source, code_variables):
                 process_section_code_variables(requirement, code_variables)
 
 
-def check_if_functional_requirements_are_specified(plain_source, non_functional_requirements):
-    if plain_source[plain_spec.NON_FUNCTIONAL_REQUIREMENTS] is not None and hasattr(
-        plain_source[plain_spec.NON_FUNCTIONAL_REQUIREMENTS], "children"
-    ):
-        non_functional_requirements.extend(plain_source[plain_spec.NON_FUNCTIONAL_REQUIREMENTS].children)
+def has_functional_specs_section(plain_source) -> bool:
+    """Whether the module declares a ***functional specs*** section (even if it is empty)."""
+    return plain_spec.FUNCTIONAL_REQUIREMENTS in plain_source
+
+
+def count_functionalities(plain_source) -> int:
+    """Number of functionalities under the ***functional specs*** section (0 if absent or empty)."""
+    section = plain_source.get(plain_spec.FUNCTIONAL_REQUIREMENTS)
+    return len(section.children) if section is not None else 0
 
-    found_functional_requirements = plain_spec.FUNCTIONAL_REQUIREMENTS in plain_source
-    if found_functional_requirements and len(non_functional_requirements) == 0:
-        raise PlainSyntaxError("Plain syntax error: functionality with no implementation reqs specified.")
 
-    return found_functional_requirements
+def validate_functionalities_have_implementation_reqs(plain_source) -> None:
+    """Raise if the module has functionalities but no implementation reqs are specified."""
+    implementation_reqs = plain_source[plain_spec.NON_FUNCTIONAL_REQUIREMENTS]
+    has_implementation_reqs = (
+        implementation_reqs is not None
+        and hasattr(implementation_reqs, "children")
+        and len(implementation_reqs.children) > 0
+    )
+    if not has_implementation_reqs:
+        raise PlainSyntaxError("Plain syntax error: functionality with no implementation reqs specified.")
 
 
 def _is_acceptance_test_heading(token) -> tuple[bool, str | None]:
@@ -390,8 +401,11 @@ def process_imports(
             module_name, code_variables, template_dirs, imported_modules, modules_trace
         )
 
-        if check_if_functional_requirements_are_specified(plain_file_parse_result.plain_source, []):
-            raise PlainSyntaxError("Plain syntax error: Imported module must not contain functionalities.")
+        if has_functional_specs_section(plain_file_parse_result.plain_source):
+            raise ImportedModuleWithFunctionalitiesError(
+                f"Module {module_name} is imported but contains functional specs. "
+                f"Imported modules may only provide definitions, implementation reqs, and test reqs."
+            )
 
         for specification_heading in plain_file_parse_result.plain_source:
             if specification_heading not in plain_spec.ALLOWED_IMPORT_SPECIFICATION_HEADINGS:
@@ -731,24 +745,21 @@ def plain_file_parser(  # noqa: C901
             f"Plain syntax error: Not all required concepts were defined. {missing_required_concepts_msg}."
         )
 
-    fr_section = plain_file_parse_result.plain_source.get(plain_spec.FUNCTIONAL_REQUIREMENTS)
-
-    if fr_section is None:
-        # Case 1: no ***functional specs*** header at all. Not a syntax error.
+    if not has_functional_specs_section(plain_file_parse_result.plain_source):
+        # No ***functional specs*** section at all: valid as an import, but not renderable. Usage error.
         raise MissingFunctionalitiesError(
             f"Module {module_name} does not have any functionality specified. "
             f"At least one functionality is required for rendering."
         )
 
-    if len(fr_section.children) == 0:
-        # Case 2: ***functional specs*** header present but empty. Treated as a syntax error.
+    if count_functionalities(plain_file_parse_result.plain_source) == 0:
+        # ***functional specs*** section present but empty: invalid in every role. Syntax error.
         raise PlainSyntaxError(
             f"Plain syntax error: Module '{module_name}' has an empty "
             f"'{plain_spec.FUNCTIONAL_REQUIREMENTS}' section. At least one functionality must be specified."
         )
 
-    # Functionalities exist: keep the existing "functionality with no implementation reqs specified" check.
-    check_if_functional_requirements_are_specified(plain_file_parse_result.plain_source, [])
+    validate_functionalities_have_implementation_reqs(plain_file_parse_result.plain_source)
 
     exported_definitions = process_required_modules(
         plain_file_parse_result.required_modules,

tests/data/imports/import_with_functionalities.plain

@@ -0,0 +1,7 @@
+***implementation reqs***
+
+- :SomeDef: is used in import_with_functionalities.
+
+***functional specs***
+
+- Display "hello, world"

tests/data/imports/imports_module_with_functionalities.plain

@@ -0,0 +1,12 @@
+---
+import:
+  - import_with_functionalities
+---
+
+***implementation reqs***
+
+- :MainExecutableFile: of :App: should be called "hello_world.py".
+
+***functional specs***
+
+- Display "hello, world"

tests/test_imports.py

@@ -1,6 +1,17 @@
 import pytest
 
 import plain_file
+from plain2code_exceptions import ImportedModuleWithFunctionalitiesError
+
+
+def test_imported_module_with_functionalities(load_test_data, get_test_data_path):
+    plain_source_text = load_test_data("data/imports/imports_module_with_functionalities.plain")
+    template_dirs = [get_test_data_path("data/imports")]
+    with pytest.raises(
+        ImportedModuleWithFunctionalitiesError,
+        match="is imported but contains functional specs",
+    ):
+        plain_file.parse_plain_source(plain_source_text, {}, template_dirs, [], [])
 
 
 def test_non_existent_import(load_test_data, get_test_data_path):