Merge pull request #2548 from haxtibal/tdmg/source_node_section_only_where_needed

fix(backend/sdoc_source_code): Don't auto-generate sections for merged source nodes

Author: stanislaw

strictdoc/core/file_traceability_index.py

@@ -16,11 +16,10 @@
 
 from strictdoc.backend.sdoc.document_reference import DocumentReference
 from strictdoc.backend.sdoc.error_handling import StrictDocSemanticError
-from strictdoc.backend.sdoc.models.document import SDocDocument
 from strictdoc.backend.sdoc.models.document_grammar import (
     DocumentGrammar,
 )
-from strictdoc.backend.sdoc.models.model import SDocDocumentIF, SDocNodeIF
+from strictdoc.backend.sdoc.models.model import SDocDocumentIF
 from strictdoc.backend.sdoc.models.node import SDocNode
 from strictdoc.backend.sdoc.models.reference import FileEntry, FileReference
 from strictdoc.backend.sdoc_source_code.models.function import Function
@@ -568,34 +567,9 @@ def validate_and_resolve(
         # STEP: Create auto-generated documents created from source file comments.
         #       Register these documents with the main traceability index.
         #
-        def create_folder_section(
-            parent__: Union[SDocDocumentIF, SDocNodeIF],
-            document__: SDocDocument,
-            path__: str,
-        ) -> SDocNode:
-            section_node = SDocNode(
-                parent=parent__,
-                node_type="SECTION",
-                fields=[],
-                relations=[],
-                is_composite=True,
-                node_type_close="SECTION",
-                # It is important that this autogenerated node is marked as such.
-                autogen=True,
-            )
-            section_node.ng_document_reference = DocumentReference()
-            section_node.ng_document_reference.set_document(document__)
-            section_node.ng_including_document_reference = DocumentReference()
-            section_node.set_field_value(
-                field_name="TITLE",
-                form_field_index=0,
-                value=path__,
-            )
-            return section_node
-
         documents_with_generated_content = set()
 
-        section_cache = {}
+        section_cache: Dict[str, Union[SDocDocumentIF, SDocNode]] = {}
         source_nodes_config: List[SourceNodesEntry] = (
             project_config.source_nodes
         )
@@ -627,24 +601,7 @@ def create_folder_section(
             document_uid = relevant_source_node_entry.uid
             document = traceability_index.get_node_by_uid(document_uid)
             documents_with_generated_content.add(document)
-
-            current_top_node = document
-            path_components = path_to_source_file_.split("/")
-            for path_component_idx_, path_component_ in enumerate(
-                path_components
-            ):
-                if path_component_ not in section_cache:
-                    path_component_title = (
-                        path_component_ + "/"
-                        if path_component_idx_ < (len(path_components) - 1)
-                        else path_component_
-                    )
-                    current_section = create_folder_section(
-                        current_top_node, document, path_component_title
-                    )
-                    current_top_node.section_contents.append(current_section)
-                    section_cache[path_component_] = current_section
-                current_top_node = section_cache[path_component_]
+            current_top_node = None
 
             for source_node_ in traceability_info_.source_nodes:
                 if len(source_node_.fields) == 0:
@@ -676,12 +633,20 @@ def create_folder_section(
                         document,
                     )
                     sdoc_node_uid = assert_cast(sdoc_node.reserved_uid, str)
-                    current_top_node.section_contents.append(sdoc_node)
                     traceability_index.graph_database.create_link(
                         link_type=GraphLinkType.UID_TO_NODE,
                         lhs_node=sdoc_node_uid,
                         rhs_node=sdoc_node,
                     )
+                    if current_top_node is None:
+                        current_top_node = (
+                            FileTraceabilityIndex.create_source_node_section(
+                                document,
+                                path_to_source_file_,
+                                section_cache,
+                            )
+                        )
+                    current_top_node.section_contents.append(sdoc_node)
 
                 self.connect_source_node_function(
                     source_node_, sdoc_node_uid, traceability_info_
@@ -1053,6 +1018,50 @@ def set_sdoc_node_fields(
                 value=field_value,
             )
 
+    @staticmethod
+    def create_source_node_section(
+        document: SDocDocumentIF,
+        path_to_source_file: str,
+        section_cache: Dict[str, Union[SDocDocumentIF, SDocNode]],
+    ) -> Union[SDocDocumentIF, SDocNode]:
+        """
+        Add a subsection for each path components in a given file path.
+        """
+        current_top_node: Union[SDocDocumentIF, SDocNode] = document
+        path_components = path_to_source_file.split("/")
+        for path_component_idx_, path_component_ in enumerate(path_components):
+            if path_component_ not in section_cache:
+                path_component_title = (
+                    path_component_ + "/"
+                    if path_component_idx_ < (len(path_components) - 1)
+                    else path_component_
+                )
+                current_section = SDocNode(
+                    parent=current_top_node,
+                    node_type="SECTION",
+                    fields=[],
+                    relations=[],
+                    is_composite=True,
+                    node_type_close="SECTION",
+                    # It is important that this autogenerated node is marked as such.
+                    autogen=True,
+                )
+                current_section.ng_document_reference = DocumentReference()
+                current_section.ng_document_reference.set_document(document)
+                current_section.ng_including_document_reference = (
+                    DocumentReference()
+                )
+                current_section.set_field_value(
+                    field_name="TITLE",
+                    form_field_index=0,
+                    value=path_component_title,
+                )
+
+                current_top_node.section_contents.append(current_section)
+                section_cache[path_component_] = current_section
+            current_top_node = section_cache[path_component_]
+        return current_top_node
+
     def connect_sdoc_node_with_file_path(
         self, sdoc_node: SDocNode, path_to_source_file_: str
     ) -> None:

tests/integration/features/source_code_traceability/_source_nodes/12_merged_functions_do_not_generate_sections/parent.sdoc

@@ -0,0 +1,12 @@
+[DOCUMENT]
+TITLE: Hello world doc
+
+[REQUIREMENT]
+UID: REQ-1
+TITLE: Requirement Title
+STATEMENT: Requirement Statement
+
+[REQUIREMENT]
+UID: REQ-2
+TITLE: Requirement Title #2
+STATEMENT: Requirement Statement #2

tests/integration/features/source_code_traceability/_source_nodes/12_merged_functions_do_not_generate_sections/source_node_base.sdoc

@@ -0,0 +1,41 @@
+[DOCUMENT]
+MID: c2d4542d5f1741c88dfcb4f68ad7dcbd
+TITLE: Requirements from Source Nodes
+UID: SRC-NODES-BASE
+
+[GRAMMAR]
+ELEMENTS:
+- TAG: SECTION
+  PROPERTIES:
+    IS_COMPOSITE: True
+  FIELDS:
+  - TITLE: UID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: TITLE
+    TYPE: String
+    REQUIRED: True
+- TAG: REQUIREMENT
+  PROPERTIES:
+    VIEW_STYLE: Narrative
+  FIELDS:
+  - TITLE: UID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: TITLE
+    TYPE: String
+    REQUIRED: False
+  - TITLE: STATEMENT
+    TYPE: String
+    REQUIRED: False
+  RELATIONS:
+  - TYPE: Parent
+  - TYPE: File
+
+[[SECTION]]
+TITLE: No need to generate a section if node is located in static section
+
+[REQUIREMENT]
+UID: REQ-EXAMPLE-1
+
+[[/SECTION]]

tests/integration/features/source_code_traceability/_source_nodes/12_merged_functions_do_not_generate_sections/src/example/example.c

@@ -0,0 +1,14 @@
+#include <stdio.h>
+
+/**
+ * Some text.
+ *
+ * UID: REQ-EXAMPLE-1
+ *
+ * TITLE: Title from example.c
+ *
+ * STATEMENT: Statement from example.c
+ */
+void example_1(void) {
+    print("hello world\n");
+}

tests/integration/features/source_code_traceability/_source_nodes/12_merged_functions_do_not_generate_sections/strictdoc.toml

@@ -0,0 +1,14 @@
+[project]
+
+features = [
+  "REQUIREMENT_TO_SOURCE_TRACEABILITY",
+  "SOURCE_FILE_LANGUAGE_PARSERS",
+]
+
+source_nodes = [
+  { "src/" = { uid = "SRC-NODES-BASE", node_type = "REQUIREMENT" } }
+]
+
+exclude_source_paths = [
+    "test.itest"
+]

tests/integration/features/source_code_traceability/_source_nodes/12_merged_functions_do_not_generate_sections/test.itest

@@ -0,0 +1,22 @@
+#
+# This test verifies that source nodes that are merged with a static SDoc node
+# do not cause auto-generation of one or more parent sections. The static node
+# is already in a static parent section. Auto-generated section with conventional
+# name would stay empty and are thus unexpected.
+#
+# @relation(SDOC-SRS-141, scope=file)
+#
+
+RUN: %strictdoc --debug export %S --output-dir %T | filecheck %s
+
+CHECK: Published: Hello world doc
+
+RUN: %check_exists --file "%T/html/_source_files/src/example/example.c.html"
+
+RUN: %cat %T/html/%THIS_TEST_FOLDER/source_node_base.html | filecheck %s --check-prefix CHECK-HTML
+CHECK-HTML: Requirements from Source Nodes
+CHECK-HTML: REQ-EXAMPLE-1
+CHECK-HTML: Title from example.c
+CHECK-HTML: src/example/example.c, <i>lines: 3-14</i>, function example_1()
+CHECK-HTML: Statement from example.c
+CHECK-HTML-NOT: <sdoc-autogen>{{.*}}example.c</sdoc-autogen>