Improve errors for modules without functionality

Distinguish two cases when a module has no functionality to render:

- No ***functional specs*** header at all: raise the new non-syntax
  MissingFunctionalitiesError with a clear, actionable message instead
  of the misleading 'was required but does not contain functional
  requirements' PlainSyntaxError.
- Empty ***functional specs*** section: raise a PlainSyntaxError naming
  the empty section, instead of silently rendering zero functionalities
  or reporting a misleading 'no implementation reqs' error.

Modules with at least one functionality still flow through the existing
implementation-reqs validation.

Author: pedjaradenkovic

plain2code.py

@@ -28,6 +28,7 @@
     InvalidAPIKey,
     InvalidFridArgument,
     MissingAPIKey,
+    MissingFunctionalitiesError,
     MissingPreviousFunctionalitiesError,
     MissingResource,
     ModuleDoesNotExistError,
@@ -65,6 +66,7 @@
     MissingResource,
     TemplateNotFoundError,
     PlainSyntaxError,
+    MissingFunctionalitiesError,
     MissingPreviousFunctionalitiesError,
     MissingAPIKey,
     InvalidAPIKey,

plain2code_exceptions.py

@@ -78,6 +78,12 @@ class MissingPreviousFunctionalitiesError(Exception):
     pass
 
 
+class MissingFunctionalitiesError(Exception):
+    """Raised when a module to be rendered has no functionalities specified at all."""
+
+    pass
+
+
 class NetworkConnectionError(Exception):
     """Raised when there is a network connectivity issue with the API server."""
 

plain_file.py

@@ -17,7 +17,12 @@
 import concept_utils
 import file_utils
 import plain_spec
-from plain2code_exceptions import ModuleDoesNotExistError, PlainSyntaxError, UnsupportedBase64Content
+from plain2code_exceptions import (
+    MissingFunctionalitiesError,
+    ModuleDoesNotExistError,
+    PlainSyntaxError,
+    UnsupportedBase64Content,
+)
 from plain2code_nodes import Plain2CodeIncludeTag, Plain2CodeLoaderMixin
 from plain2code_utils import find_large_base64_blob
 
@@ -726,11 +731,25 @@ def plain_file_parser(  # noqa: C901
             f"Plain syntax error: Not all required concepts were defined. {missing_required_concepts_msg}."
         )
 
-    if not check_if_functional_requirements_are_specified(plain_file_parse_result.plain_source, []):
+    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.
+        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.
         raise PlainSyntaxError(
-            f"Plain syntax error: Module '{module_name}' was required but does not contain functional requirements."
+            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, [])
+
     exported_definitions = process_required_modules(
         plain_file_parse_result.required_modules,
         code_variables={},

tests/data/plainfile/empty_functional_specs_section.plain

@@ -0,0 +1,4 @@
+***implementation reqs***
+- Some requirement
+
+***functional specs***

tests/data/plainfile/no_functional_specs_section.plain

@@ -0,0 +1,5 @@
+***definitions***
+- Test definition
+
+***implementation reqs***
+- Some requirement

tests/test_plainfileparser.py

@@ -9,7 +9,7 @@
 import file_utils
 import plain_file
 import plain_spec
-from plain2code_exceptions import PlainSyntaxError
+from plain2code_exceptions import MissingFunctionalitiesError, PlainSyntaxError
 
 
 def test_regular_plain_source(get_test_data_path):
@@ -195,6 +195,28 @@ def test_without_non_functional_requirement(get_test_data_path):
         )
 
 
+def test_no_functional_specs_section(get_test_data_path):
+    with pytest.raises(
+        MissingFunctionalitiesError,
+        match="does not have any functionality specified",
+    ):
+        plain_file.plain_file_parser(
+            "no_functional_specs_section.plain",
+            [get_test_data_path("data/plainfile")],
+        )
+
+
+def test_empty_functional_specs_section(get_test_data_path):
+    with pytest.raises(
+        PlainSyntaxError,
+        match=re.escape("has an empty 'functional specs' section"),
+    ):
+        plain_file.plain_file_parser(
+            "empty_functional_specs_section.plain",
+            [get_test_data_path("data/plainfile")],
+        )
+
+
 def test_indented_include_tags():
     plain_source = """# Main