Enhance validation for graph checks error messages (#142)

Author: Aymen-Soussi-01

src/extensions/score_metamodel/__init__.py

@@ -170,7 +170,6 @@ def load_metamodel_data():
     types_dict = data.get("needs_types", {})
     links_dict = data.get("needs_extra_links", {})
     graph_check_dict = data.get("graph_checks", {})
-
     global_base_options = data.get("needs_types_base_options", {})
     global_base_options_optional_opts = global_base_options.get("optional_options", {})
 

src/extensions/score_metamodel/checks/graph_checks.py

@@ -12,15 +12,15 @@
 # *******************************************************************************
 import operator
 from collections.abc import Callable
-from typing import Any, Literal
-
-from sphinx.application import Sphinx
-from sphinx_needs.data import NeedsInfoType, NeedsView
+from functools import reduce
+from typing import Any
 
 from score_metamodel import (
     CheckLogger,
     graph_check,
 )
+from sphinx.application import Sphinx
+from sphinx_needs.data import NeedsInfoType, NeedsView
 
 
 def eval_need_check(need: NeedsInfoType, check: str, log: CheckLogger) -> bool:
@@ -70,7 +70,7 @@ def eval_need_condition(
     oper: dict[str, Any] = {
         "and": operator.and_,
         "or": operator.or_,
-        "not": operator.not_,
+        "not": lambda x: not x,
         "xor": operator.xor,
     }
 
@@ -80,16 +80,17 @@ def eval_need_condition(
     cond: str = list(condition.keys())[0]
     vals: list[Any] = list(condition.values())[0]
 
-    if cond in ["and", "or", "xor", "not"]:
-        for i in range(len(vals) - 1):
-            return oper[cond](
-                eval_need_condition(need, vals[i], log),
-                eval_need_condition(need, vals[i + 1], log),
-            )
-    else:
-        raise ValueError(f"Binary Operator not defined: {vals}")
+    if cond == "not":
+        if not isinstance(vals, list) or len(vals) != 1:
+            raise ValueError("Operator 'not' requires exactly one operand.")
+        return oper["not"](eval_need_condition(need, vals[0], log))
 
-    return True
+    if cond in ["and", "or", "xor"]:
+        return reduce(
+            lambda a, b: oper[cond](a, b),
+            (eval_need_condition(need, val, log) for val in vals),
+        )
+    raise ValueError(f"Unsupported condition operator: {cond}")
 
 
 def get_need_selection(
@@ -137,18 +138,25 @@ def check_metamodel_graph(
     # Convert list to dictionary for easy lookup
     needs_dict_all = {need["id"]: need for need in all_needs.values()}
     needs_local = list(all_needs.filter_is_external(False).values())
+
     # Iterate over all graph checks
-    for check in graph_checks_global.items():
-        apply, eval = check[1].values()
-        # Get all needs that match the selection criteria
+    for check_name, check_config in graph_checks_global.items():
+        apply = check_config.get("needs")
+        eval = check_config.get("check")
+        explanation = check_config.get("explanation", "")
+        assert explanation != "", (
+            f"Explanation for graph check {check_name} is missing. Explanations are mandatory for graph checks."
+        )
+        # Get all needs matching the selection criteria
         selected_needs = get_need_selection(needs_local, apply, log)
 
         for need in selected_needs:
             for parent_relation in list(eval.keys()):
                 if parent_relation not in need:
-                    msg = f"Attribute not defined: {parent_relation}"
+                    msg = f"Attribute not defined: `{parent_relation}` in need `{need['id']}`."
                     log.warning_for_need(need, msg)
                     continue
+
                 parent_ids = need[parent_relation]
 
                 for parent_id in parent_ids:
@@ -160,7 +168,8 @@ def check_metamodel_graph(
 
                     if not eval_need_condition(parent_need, eval[parent_relation], log):
                         msg = (
-                            f"parent need `{parent_id}` does not fulfill "
+                            f"Parent need `{parent_id}` does not fulfill "
                             f"condition `{eval[parent_relation]}`."
+                            f" Explanation: {explanation}"
                         )
                         log.warning_for_need(need, msg)

src/extensions/score_metamodel/metamodel.yaml

@@ -18,7 +18,7 @@ needs_types_base_options:
     # Custom semantic validation rules
 
 # Prohibited Word Option Checks
-# Follow this schema to write new checks 
+# Follow this schema to write new checks
 # check_name:
 # types[optional]:
 #   - List of tag types ('tags' option)
@@ -821,6 +821,7 @@ graph_checks:
       condition: safety == QM
     check:
       satisfies: safety == QM
+    explanation: An ASIL requirement must link at least one parent/upstream ASIL requirement for correct decomposition. Please ensure the parent’s safety level is QM and its status is valid.
   # If need-req is `ASIL_B`, parent must be `QM` or `ASIL_B`.
   req_safety_linkage_asil_b:
     needs:
@@ -831,6 +832,7 @@ graph_checks:
         or:
           - safety == ASIL_B
           - safety == QM
+    explanation: An ASIL requirement must link at least one parent/upstream ASIL requirement for correct decomposition. Please ensure the parent’s safety level is ASIL_B or QM and its status is valid.
   # saf - ID gd_req__saf_linkage_safety
   # It shall be checked that Safety Analysis (DFA and FMEA) can only be linked via mitigate against
   #  - <Feature | Component | AoU> Requirements with the same ASIL or
@@ -842,4 +844,4 @@ graph_checks:
       condition: safety == ASIL_B
     check:
       mitigated_by: safety != QM
-
+    explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.

src/extensions/score_metamodel/tests/rst/graph/test_metamodel_graph.rst

@@ -31,16 +31,17 @@
 
 
 .. Positive Test: Child requirement QM. Parent requirement has the correct related safety level. Parent requirement is `QM`.
-#EXPECT-NOT: feat_req__child__1: parent need `feat_req__parent__QM` does not fulfill condition `safety == QM`.
+#EXPECT-NOT: feat_req__child__1: Parent need `feat_req__parent__QM` does not fulfill condition `safety == QM`. Explanation: An ASIL requirement must link at least one parent/upstream ASIL requirement for correct decomposition. Please ensure the parent’s safety level is QM and its status is valid.
 
 .. feat_req:: Child requirement 1
    :id: feat_req__child__1
    :safety: QM
    :satisfies: feat_req__parent__QM
    :status: valid
 
+
 .. Positive Test: Child requirement ASIL B. Parent requirement has the correct related safety level. Parent requirement is `QM`.
-#EXPECT-NOT: feat_req__child__2: parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety == QM`.
+#EXPECT-NOT: feat_req__child__2: Parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety == QM`. Explanation: An ASIL requirement must link at least one parent/upstream ASIL requirement for correct decomposition. Please ensure the parent’s safety level is QM and its status is valid.
 
 .. feat_req:: Child requirement 2
    :id: feat_req__child__2
@@ -49,130 +50,139 @@
    :status: valid
 
 
+
 .. Negative Test: Child requirement QM. Parent requirement is `ASIL_B`. Child cant fulfill the safety level of the parent.
-#EXPECT: feat_req__child__4: parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety == QM`.
+#EXPECT: feat_req__child__3: Parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety == QM`. Explanation: An ASIL requirement must link at least one parent/upstream ASIL requirement for correct decomposition. Please ensure the parent’s safety level is QM and its status is valid.
 
-.. comp_req:: Child requirement 4
-   :id: feat_req__child__4
+.. comp_req:: Child requirement 3
+   :id: feat_req__child__3
    :safety: QM
    :satisfies: feat_req__parent__ASIL_B
    :status: valid
 
 
 
-
-
 .. Parent requirement does not exist
-#EXPECT: feat_req__child__9: Parent need `feat_req__parent0__abcd` not found in needs_dict.
+#EXPECT: feat_req__child__4: Parent need `feat_req__parent0__abcd` not found in needs_dict.
 
-.. feat_req:: Child requirement 9
-   :id: feat_req__child__9
+.. feat_req:: Child requirement 4
+   :id: feat_req__child__4
    :safety: ASIL_B
    :status: valid
    :satisfies: feat_req__parent0__abcd
 
 
+
 .. Mitigation of Safety Analysis (FMEA and DFA) shall be checked. Mitigation shall have the same or higher safety level than the analysed item.
 .. Negative Test: Linked to a mitigation that is lower than the safety level of the analysed item.
-#EXPECT: feat_saf_dfa__child__10: parent need `feat_req__parent__QM` does not fulfill condition `safety != QM`.
+#EXPECT: feat_saf_dfa__child__5: Parent need `feat_req__parent__QM` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. feat_saf_dfa:: Child requirement 10
-   :id: feat_saf_dfa__child__10
+.. feat_saf_dfa:: Child requirement 5
+   :id: feat_saf_dfa__child__5
    :safety: ASIL_B
    :status: valid
    :mitigated_by: feat_req__parent__QM
 
+
 .. Positive Test: Linked to a mitigation that is equal to the safety level of the analysed item.
-#EXPECT-NOT: feat_saf_dfa__child__11: parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`.
+#EXPECT-NOT: feat_saf_dfa__child__6: Parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. feat_saf_dfa:: Child requirement 11
-   :id: feat_saf_dfa__child__11
+.. feat_saf_dfa:: Child requirement 6
+   :id: feat_saf_dfa__child__6
    :safety: ASIL_B
    :status: valid
    :mitigated_by: feat_req__parent__ASIL_B
 
 
+
 .. Negative Test: Linked to a mitigation that is lower than the safety level of the analysed item.
-#EXPECT: comp_saf_dfa__child__13: parent need `feat_req__parent__QM` does not fulfill condition `safety != QM`.
+#EXPECT: comp_saf_dfa__child__7: Parent need `feat_req__parent__QM` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. comp_saf_dfa:: Child requirement 13
-   :id: comp_saf_dfa__child__13
+.. comp_saf_dfa:: Child requirement 7
+   :id: comp_saf_dfa__child__7
    :safety: ASIL_B
    :status: valid
    :mitigated_by: feat_req__parent__QM
 
+
 .. Positive Test: Linked to a mitigation that is equal to the safety level of the analysed item.
-#EXPECT-NOT: comp_saf_dfa__child__14: parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`.
+#EXPECT-NOT: comp_saf_dfa__child__8: Parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. comp_saf_dfa:: Child requirement 14
-   :id: comp_saf_dfa__child__14
+.. comp_saf_dfa:: Child requirement 8
+   :id: comp_saf_dfa__child__8
    :safety: ASIL_B
    :status: valid
    :mitigated_by: feat_req__parent__ASIL_B
 
 
+
 .. Negative Test: Linked to a mitigation that is lower than the safety level of the analysed item.
-#EXPECT: feat_saf_dfa__child__16: parent need `feat_req__parent__QM` does not fulfill condition `safety != QM`.
+#EXPECT: feat_saf_dfa__child__9: Parent need `feat_req__parent__QM` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. feat_saf_dfa:: Child requirement 16
-   :id: feat_saf_dfa__child__16
+.. feat_saf_dfa:: Child requirement 9
+   :id: feat_saf_dfa__child__9
    :safety: ASIL_B
    :status: valid
    :mitigated_by: feat_req__parent__QM
 
+
 .. Positive Test: Linked to a mitigation that is equal to the safety level of the analysed item.
-#EXPECT-NOT: feat_saf_dfa__child__17: parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`.
+#EXPECT-NOT: feat_saf_dfa__child__10: Parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. feat_saf_dfa:: Child requirement 17
-   :id: feat_saf_dfa__child__17
+.. feat_saf_dfa:: Child requirement 10
+   :id: feat_saf_dfa__child__10
    :safety: ASIL_B
    :status: valid
    :mitigated_by: feat_req__parent__ASIL_B
 
 
+
 .. Negative Test: Linked to a mitigation that is lower than the safety level of the analysed item.
-#EXPECT: feat_saf_fmea__child__19: parent need `feat_req__parent__QM` does not fulfill condition `safety != QM`.
+#EXPECT: feat_saf_fmea__child__11: Parent need `feat_req__parent__QM` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. feat_saf_fmea:: Child requirement 19
-   :id: feat_saf_fmea__child__19
+.. feat_saf_fmea:: Child requirement 11
+   :id: feat_saf_fmea__child__11
    :safety: ASIL_B
    :status: valid
    :mitigated_by: feat_req__parent__QM
 
+
 .. Positive Test: Linked to a mitigation that is equal to the safety level of the analysed item.
-#EXPECT-NOT: feat_saf_fmea__child__20: parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`.
+#EXPECT-NOT: feat_saf_fmea__child__12: Parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. feat_saf_fmea:: Child requirement 20
-   :id: feat_saf_fmea__child__20
+.. feat_saf_fmea:: Child requirement 12
+   :id: feat_saf_fmea__child__12
    :safety: ASIL_B
    :status: valid
    :mitigated_by: feat_req__parent__ASIL_B
 
 
+
 .. Positive Test: Linked to a mitigation that is higher to the safety level of the analysed item.
-#EXPECT-NOT: feat_saf_fmea__child__21: parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`.
+#EXPECT-NOT: feat_saf_fmea__child__13: Parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. feat_saf_fmea:: Child requirement 21
-   :id: feat_saf_fmea__child__21
+.. feat_saf_fmea:: Child requirement 13
+   :id: feat_saf_fmea__child__13
    :safety: QM
    :status: valid
    :mitigated_by: feat_req__parent__ASIL_B
 
+
 .. Negative Test: Linked to a mitigation that is lower than the safety level of the analysed item.
-#EXPECT: comp_saf_fmea__child__22: parent need `feat_req__parent__QM` does not fulfill condition `safety != QM`.
+#EXPECT: comp_saf_fmea__child__14: Parent need `feat_req__parent__QM` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. comp_saf_fmea:: Child requirement 22
-   :id: comp_saf_fmea__child__22
+.. comp_saf_fmea:: Child requirement 14
+   :id: comp_saf_fmea__child__14
    :safety: ASIL_B
    :status: valid
    :mitigated_by: feat_req__parent__QM
 
+
 .. Positive Test: Linked to a mitigation that is equal to the safety level of the analysed item.
-#EXPECT-NOT: comp_saf_fmea__child__23: parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`.
+#EXPECT-NOT: comp_saf_fmea__child__15: Parent need `feat_req__parent__ASIL_B` does not fulfill condition `safety != QM`. Explanation: An ASIL_B safety requirement must link to a ASIL_B requirement. Please ensure that the linked requirements safety level is not QM and it's status is valid.
 
-.. comp_saf_fmea:: Child requirement 23
-   :id: comp_saf_fmea__child__23
+.. comp_saf_fmea:: Child requirement 15
+   :id: comp_saf_fmea__child__15
    :safety: ASIL_B
    :status: valid
    :mitigated_by: feat_req__parent__ASIL_B
-