Merge pull request strictdoc-project#1309 from strictdoc-project/stan…

…islaw/relations_1 sdoc/grammar: introduce REFS/RELATIONS/ROLES
GGBeer · Sep 22, 2023 · 2a08dfa · 2a08dfa
2 parents 9600186 + 6b1a18b
commit 2a08dfa
Show file tree

Hide file tree

Showing 56 changed files with 1,984 additions and 1,143 deletions.
diff --git a/docs/strictdoc_20_requirements.sdoc b/docs/strictdoc_20_requirements.sdoc
@@ -11,9 +11,6 @@ ELEMENTS:
   - TITLE: UID
     TYPE: String
     REQUIRED: False
-  - TITLE: REFS
-    TYPE: String
-    REQUIRED: False
   - TITLE: TITLE
     TYPE: String
     REQUIRED: True
@@ -26,6 +23,9 @@ ELEMENTS:
   - TITLE: COMMENT
     TYPE: String
     REQUIRED: False
+  RELATIONS:
+  - TYPE: Parent
+  - TYPE: File
 
 [FREETEXT]
 This document is a collection of high-level requirements for StrictDoc as well as some of its middle-level requirements. The existing requirements set is pending a proper functional decomposition/partitioning following the creation of bidirectional traces between the requirements and StrictDoc's source code.
@@ -36,13 +36,13 @@ TITLE: High-level requirements
 
 [REQUIREMENT]
 UID: SDOC-HIGH-REQS-MANAGEMENT
-REFS:
-- TYPE: Parent
-  VALUE: GOAL-1-TOOL-SUPPORT
 TITLE: Requirements management
 STATEMENT: >>>
 StrictDoc shall enable requirements management.
 <<<
+REFS:
+- TYPE: Parent
+  VALUE: GOAL-1-TOOL-SUPPORT
 
 [REQUIREMENT]
 UID: SDOC-HIGH-DATA-MODEL
@@ -127,11 +127,6 @@ TITLE: Data model
 
 [REQUIREMENT]
 UID: SDOC-DM-MODEL
-REFS:
-- TYPE: Parent
-  VALUE: SDOC-HIGH-REQS-MANAGEMENT
-- TYPE: Parent
-  VALUE: SDOC-HIGH-DATA-MODEL
 TITLE: Modeling capability
 STATEMENT: StrictDoc's Data Model shall accommodate for maximum possible standard requirement document formats.
 COMMENT: >>>
@@ -140,6 +135,11 @@ Examples of standard requirements documents include but are not limited to:
 - Non-nested requirement lists split by categories
   (e.g., Functional Requirements, Interface Requirements, Performance Requirements, etc.)
 <<<
+REFS:
+- TYPE: Parent
+  VALUE: SDOC-HIGH-REQS-MANAGEMENT
+- TYPE: Parent
+  VALUE: SDOC-HIGH-DATA-MODEL
 
 [SECTION]
 TITLE: Project
@@ -281,24 +281,24 @@ TITLE: SDoc file format
 
 [REQUIREMENT]
 UID: SDOC-FMT-PRIMARY
+TITLE: Primary text implementation
+STATEMENT: The SDoc format shall support encoding the Strict Doc Data Model in a plain-text human readable form.
 REFS:
 - TYPE: Parent
   VALUE: SDOC-DM-MODEL
-TITLE: Primary text implementation
-STATEMENT: The SDoc format shall support encoding the Strict Doc Data Model in a plain-text human readable form.
 
 [SECTION]
 TITLE: Grammar
 
 [REQUIREMENT]
 UID: SDOC-FMT-GRAMMAR
+TITLE: Grammar
+STATEMENT: The SDoc format shall be based on a fixed grammar.
 REFS:
 - TYPE: Parent
   VALUE: SDOC-HIGH-DATA-MODEL
 - TYPE: File
   VALUE: strictdoc/backend/sdoc/grammar/grammar.py
-TITLE: Grammar
-STATEMENT: The SDoc format shall be based on a fixed grammar.
 
 [REQUIREMENT]
 TITLE: No indentation
@@ -346,18 +346,18 @@ TITLE: Single document: Tabular form
 STATEMENT: StrictDoc shall export single document pages in a tabular form.
 
 [REQUIREMENT]
+TITLE: Single document: 1-level traceability
+STATEMENT: StrictDoc shall export 1-level traceability document.
 REFS:
 - TYPE: Parent
   VALUE: SDOC-HIGH-REQS-TRACEABILITY
-TITLE: Single document: 1-level traceability
-STATEMENT: StrictDoc shall export 1-level traceability document.
 
 [REQUIREMENT]
+TITLE: Single document: Deep traceability
+STATEMENT: StrictDoc shall export deep traceability document.
 REFS:
 - TYPE: Parent
   VALUE: SDOC-HIGH-REQS-TRACEABILITY
-TITLE: Single document: Deep traceability
-STATEMENT: StrictDoc shall export deep traceability document.
 
 [REQUIREMENT]
 TITLE: Left panel: Table of contents
@@ -376,11 +376,11 @@ STATEMENT: StrictDoc shall support exporting documents to Sphinx/RST format.
 
 [REQUIREMENT]
 UID: SDOC-GEN-EXCEL-EXPORT
+TITLE: Excel Export
+STATEMENT: StrictDoc shall support exporting documents to Excel format.
 REFS:
 - TYPE: File
   VALUE: strictdoc/backend/excel/export/excel_generator.py
-TITLE: Excel Export
-STATEMENT: StrictDoc shall support exporting documents to Excel format.
 
 [REQUIREMENT]
 TITLE: ReqIF import/export
@@ -393,35 +393,35 @@ TITLE: Validation
 
 [REQUIREMENT]
 UID: SDOC-VALIDATION-UNIQUE-UID
-REFS:
-- TYPE: Parent
-  VALUE: SDOC-HIGH-VALIDATION
 TITLE: Uniqueness of UID identifiers in a document tree
 STATEMENT: StrictDoc shall ensure that each UID used in a document tree is unique.
 COMMENT: This is implemented but the error message shall be made more readable.
+REFS:
+- TYPE: Parent
+  VALUE: SDOC-HIGH-VALIDATION
 
 [REQUIREMENT]
 UID: SDOC-VALIDATION-NO-CYCLES
+TITLE: No cycles in a document tree
+STATEMENT: >>>
+StrictDoc shall ensure that no requirements in document tree reference each other.
+<<<
 REFS:
 - TYPE: Parent
   VALUE: SDOC-HIGH-VALIDATION
 - TYPE: File
   VALUE: strictdoc/core/tree_cycle_detector.py
 - TYPE: File
   VALUE: strictdoc/core/traceability_index_builder.py
-TITLE: No cycles in a document tree
-STATEMENT: >>>
-StrictDoc shall ensure that no requirements in document tree reference each other.
-<<<
 
 [REQUIREMENT]
 UID: SDOC-VALIDATION-VALID-HTML
-REFS:
-- TYPE: Parent
-  VALUE: SDOC-HIGH-VALIDATION
 TITLE: Valid HTML markup
 STATEMENT: StrictDoc's HTML export tests shall validate the generated HTML markup.
 COMMENT: First candidate: Table of contents and its nested ``<ul>/<li>`` items.
+REFS:
+- TYPE: Parent
+  VALUE: SDOC-HIGH-VALIDATION
 
 [/SECTION]
 
@@ -476,11 +476,11 @@ TITLE: Implementation requirements
 
 [REQUIREMENT]
 UID: SDOC-IMPL-PARAL
+TITLE: Parallelization
+STATEMENT: StrictDoc shall enable parallelization of the time-consuming parts of the code.
 REFS:
 - TYPE: File
   VALUE: strictdoc/helpers/parallelizer.py
-TITLE: Parallelization
-STATEMENT: StrictDoc shall enable parallelization of the time-consuming parts of the code.
 
 [REQUIREMENT]
 UID: SDOC-IMPL-INCREMENTAL

diff --git a/docs/strictdoc_21_design.sdoc b/docs/strictdoc_21_design.sdoc
@@ -140,9 +140,6 @@ ReqIF format does not seem to provide a dedicated convention for a text node to
 
 [REQUIREMENT]
 UID: SDOC_IMPL_2
-REFS:
-- TYPE: File
-  VALUE: strictdoc/helpers/parallelizer.py
 TITLE: SDOC_IMPL_2: Running out of semaphores on macOS
 STATEMENT: >>>
 This an edge case on macOS: Python crashes in the Parallelizer class when
@@ -159,5 +156,8 @@ The fragment of the crash:
     sl = self._semlock = _multiprocessing.SemLock(
     OSError: [Errno 28] No space left on device
 <<<
+REFS:
+- TYPE: File
+  VALUE: strictdoc/helpers/parallelizer.py
 
 [/SECTION]
diff --git a/strictdoc/__init__.py b/strictdoc/__init__.py
@@ -1,6 +1,6 @@
 from strictdoc.core.environment import SDocRuntimeEnvironment
 
-__version__ = "0.0.44a11"
+__version__ = "0.0.44a12"
 
 
 environment = SDocRuntimeEnvironment(__file__)
diff --git a/strictdoc/backend/excel/import_/excel_to_sdoc_converter.py b/strictdoc/backend/excel/import_/excel_to_sdoc_converter.py
@@ -122,7 +122,11 @@ def create_document(title: Optional[str], extra_header_pairs) -> Document:
         document_title = title if title else "<No title>"
         document = Document(document_title, document_config, None, [], [])
 
-        fields = DocumentGrammar.create_default(document).elements[0].fields
+        fields = list(
+            DocumentGrammar.create_default(document).elements[0].fields
+        )
+        refs_index = len(fields) - 1
+
         for _, name in extra_header_pairs:
             fields.extend(
                 [
@@ -132,8 +136,14 @@ def create_document(title: Optional[str], extra_header_pairs) -> Document:
                 ]
             )
 
+        # Here, we want to make sure that the REFS grammar field still shows up
+        # in the grammar **after** all fields, including the custom fields.
+        # FIXME: The REFS field configuration will become a standalone entity
+        # in the grammar, it will not longer be kept inside the grammar fields.
+        fields.insert(len(fields) - 1, fields.pop(refs_index))
+
         requirements_element = GrammarElement(
-            parent=None, tag="REQUIREMENT", fields=fields
+            parent=None, tag="REQUIREMENT", fields=fields, relations=[]
         )
         elements = [requirements_element]
         grammar = DocumentGrammar(parent=document, elements=elements)
@@ -176,9 +186,21 @@ def create_requirement(
             tags=None,
             comments=comments,
         )
+        for i, name in columns.extra_header_pairs:
+            value = row_values[i].strip()
+            if value != "":
+                template_requirement.ordered_fields_lookup[name] = [
+                    RequirementField(
+                        parent=None,
+                        field_name=name,
+                        field_value=None,
+                        field_value_multiline=value,
+                        field_value_references=None,
+                    )
+                ]
         if parent_uid is not None:
             reference = ParentReqReference(
-                template_requirement, parent_uid, relation_uid=None
+                template_requirement, parent_uid, role_uid=None
             )
 
             requirement_field = RequirementField(
@@ -191,20 +213,6 @@ def create_requirement(
             template_requirement.ordered_fields_lookup["REFS"] = [
                 requirement_field
             ]
-
-        for i, name in columns.extra_header_pairs:
-            value = row_values[i].strip()
-            if value != "":
-                template_requirement.ordered_fields_lookup[name] = [
-                    RequirementField(
-                        parent=None,
-                        field_name=name,
-                        field_value=None,
-                        field_value_multiline=value,
-                        field_value_references=None,
-                    )
-                ]
-
         requirement = Requirement(
             parent=template_requirement.parent,
             requirement_type=template_requirement.requirement_type,

diff --git a/strictdoc/backend/reqif/p01_sdoc/reqif_to_sdoc_converter.py b/strictdoc/backend/reqif/p01_sdoc/reqif_to_sdoc_converter.py
@@ -250,7 +250,7 @@ def create_grammar_element_from_spec_object_type(
             else:
                 raise NotImplementedError(attribute) from None
         requirement_element = GrammarElement(
-            parent=None, tag="REQUIREMENT", fields=fields
+            parent=None, tag="REQUIREMENT", fields=fields, relations=[]
         )
         return requirement_element
 
@@ -432,7 +432,7 @@ def create_requirement_from_spec_object(
                         parent_spec_object_parent.attribute_map[
                             foreign_key_id_or_none
                         ].value,
-                        relation_uid=None,
+                        role_uid=None,
                     )
                 )
             if len(parent_refs) > 0:

diff --git a/strictdoc/backend/reqif/p11_polarion/reqif_to_sdoc_converter.py b/strictdoc/backend/reqif/p11_polarion/reqif_to_sdoc_converter.py
@@ -279,7 +279,7 @@ def _p11_create_grammar_element_from_spec_object_type(
             else:
                 raise NotImplementedError(attribute) from None
         requirement_element = GrammarElement(
-            parent=None, tag="REQUIREMENT", fields=fields
+            parent=None, tag="REQUIREMENT", fields=fields, relations=[]
         )
         return requirement_element
 
@@ -442,7 +442,7 @@ def _p11_create_requirement_from_spec_object(
                         parent_spec_object_parent.attribute_map[
                             foreign_key_id_or_none
                         ].value,
-                        relation_uid=None,
+                        role_uid=None,
                     )
                 )
             if len(parent_refs) > 0:

diff --git a/strictdoc/backend/reqif/sdoc_reqif_fields.py b/strictdoc/backend/reqif/sdoc_reqif_fields.py
@@ -55,11 +55,11 @@ class ReqIFChapterField:
     "LEVEL",
     "STATUS",
     "TAGS",
-    "REFS",
     "ReqIF.Name",
     "ReqIF.Text",
     "RATIONALE",
     "NOTES",
+    "REFS",
     "ReqIF.ChapterName",
 ]
 

diff --git a/strictdoc/backend/sdoc/grammar/grammar.py b/strictdoc/backend/sdoc/grammar/grammar.py
@@ -53,6 +53,28 @@
   '- TAG: ' tag = RequirementType '\n'
   '  FIELDS:' '\n'
   fields += GrammarElementField
+  (
+    '  RELATIONS:' '\n'
+    relations += GrammarElementRelation
+  )?
+;
+
+GrammarElementRelation[noskipws]:
+  (GrammarElementRelationParent | GrammarElementRelationChild | GrammarElementRelationFile)
+;
+
+GrammarElementRelationParent[noskipws]:
+  '  - TYPE: ' relation_type='Parent' '\n'
+  ('    ROLE: ' relation_role=/.+/ '\n')?
+;
+
+GrammarElementRelationChild[noskipws]:
+  '  - TYPE: ' relation_type='Child' '\n'
+  ('    ROLE: ' relation_role=/.+/ '\n')?
+;
+
+GrammarElementRelationFile[noskipws]:
+  '  - TYPE: ' relation_type='File' '\n'
 ;
 
 GrammarElementField[noskipws]:

diff --git a/strictdoc/backend/sdoc/grammar/type_system.py b/strictdoc/backend/sdoc/grammar/type_system.py
@@ -28,7 +28,7 @@
 ParentReqReference[noskipws]:
   '- TYPE: Parent' '\n'
   '  VALUE: ' ref_uid = /.*$/ '\n'
-  ('  RELATION: ' relation_uid = /.+$/ '\n')?
+  ('  ROLE: ' role_uid = /.+$/ '\n')?
 ;
 
 ChildReqReference[noskipws]:

diff --git a/strictdoc/backend/sdoc/models/constants.py b/strictdoc/backend/sdoc/models/constants.py
@@ -29,6 +29,9 @@
     GrammarElementFieldSingleChoice,
     GrammarElementFieldString,
     GrammarElementFieldTag,
+    GrammarElementRelationChild,
+    GrammarElementRelationFile,
+    GrammarElementRelationParent,
 )
 
 SECTION_MODELS = [
@@ -59,6 +62,9 @@
     GrammarElementFieldMultipleChoice,
     GrammarElementFieldTag,
     GrammarElementFieldReference,
+    GrammarElementRelationParent,
+    GrammarElementRelationChild,
+    GrammarElementRelationFile,
 ]
 DOCUMENT_MODELS.extend(SECTION_MODELS)