feat(backend/sdoc_source_code): Support merge by MID

Until now, finding a static merge candidate for source nodes relied on
having a UID field set at source code side. Now we can also use MIDs
for this purpose.

Author: haxtibal

strictdoc/core/file_traceability_index.py

@@ -47,6 +47,7 @@
 from strictdoc.helpers.cast import assert_cast
 from strictdoc.helpers.exception import StrictDocException
 from strictdoc.helpers.google_test import convert_function_name_to_gtest_macro
+from strictdoc.helpers.mid import MID
 from strictdoc.helpers.ordered_set import OrderedSet
 
 if TYPE_CHECKING:
@@ -608,15 +609,50 @@ def validate_and_resolve(
                     continue
 
                 assert source_node_.entity_name is not None
+                sdoc_node = None
                 sdoc_node_uid = source_node_.get_sdoc_field(
                     "UID", relevant_source_node_entry
                 )
-                if sdoc_node_uid is None:
-                    sdoc_node_uid = f"{document_uid}/{path_to_source_file_}/{source_node_.entity_name}"
-                sdoc_node = traceability_index.get_node_by_uid_weak(
-                    sdoc_node_uid
+                mid = source_node_.get_sdoc_field(
+                    "MID", relevant_source_node_entry
                 )
 
+                # First merge criterion: Merge if SDoc node with same MID exists.
+                if mid is not None:
+                    sdoc_node_mid = MID(mid)
+                    merge_candidate_sdoc_node = (
+                        traceability_index.get_node_by_mid_weak(sdoc_node_mid)
+                    )
+                    if merge_candidate_sdoc_node is not None:
+                        merge_candidate_sdoc_node = assert_cast(
+                            merge_candidate_sdoc_node, SDocNode
+                        )
+                        # Simplification: Either SDoc must have a static UID that is not overwritten by source node.
+                        if (
+                            merge_candidate_sdoc_node.reserved_uid is not None
+                            and (
+                                merge_candidate_sdoc_node.reserved_uid
+                                == sdoc_node_uid
+                                or sdoc_node_uid is None
+                            )
+                        ):
+                            sdoc_node_uid = (
+                                merge_candidate_sdoc_node.reserved_uid
+                            )
+                            sdoc_node = merge_candidate_sdoc_node
+
+                if sdoc_node is None:
+                    # If no UID from source code field or merge-by-MID, create UID by conventional scheme.
+                    if sdoc_node_uid is None:
+                        sdoc_node_uid = f"{document_uid}/{path_to_source_file_}/{source_node_.entity_name}"
+                    # Second merge criterion: Merge if SDoc node with same UID exists.
+                    tmp_sdoc_node = traceability_index.get_node_by_uid_weak(
+                        sdoc_node_uid
+                    )
+                    if isinstance(tmp_sdoc_node, SDocNode):
+                        sdoc_node = tmp_sdoc_node
+
+                assert sdoc_node_uid is not None
                 if sdoc_node is not None:
                     sdoc_node = assert_cast(sdoc_node, SDocNode)
                     self.merge_sdoc_node_with_source_node(
@@ -633,11 +669,6 @@ def validate_and_resolve(
                         document,
                     )
                     sdoc_node_uid = assert_cast(sdoc_node.reserved_uid, str)
-                    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(
@@ -971,6 +1002,11 @@ def create_sdoc_node_from_source_node(
         ):
             sdoc_node_fields["TITLE"] = source_node.entity_name
         FileTraceabilityIndex.set_sdoc_node_fields(sdoc_node, sdoc_node_fields)
+        if "MID" in sdoc_node_fields:
+            mid = sdoc_node_fields["MID"]
+            sdoc_node.reserved_mid = MID(mid)
+            if parent_document.config.enable_mid:
+                sdoc_node.mid_permanent = True
         return sdoc_node
 
     @staticmethod
@@ -1007,6 +1043,10 @@ def merge_sdoc_node_with_source_node(
         sdoc_node_fields = source_node.get_sdoc_fields(source_node_config_entry)
         FileTraceabilityIndex.set_sdoc_node_fields(sdoc_node, sdoc_node_fields)
 
+        if "MID" in sdoc_node_fields:
+            mid = sdoc_node_fields["MID"]
+            sdoc_node.reserved_mid = MID(mid)
+
     @staticmethod
     def set_sdoc_node_fields(
         sdoc_node: SDocNode, sdoc_node_fields: dict[str, str]
@@ -1088,6 +1128,31 @@ def connect_source_node_requirements(
 
         Here we link REQ and sdoc_node bidirectional.
         """
+        if (
+            sdoc_node.reserved_uid is not None
+            and not traceability_index.graph_database.has_link(
+                link_type=GraphLinkType.UID_TO_NODE,
+                lhs_node=sdoc_node.reserved_uid,
+                rhs_node=sdoc_node,
+            )
+        ):
+            traceability_index.graph_database.create_link(
+                link_type=GraphLinkType.UID_TO_NODE,
+                lhs_node=sdoc_node.reserved_uid,
+                rhs_node=sdoc_node,
+            )
+
+        if not traceability_index.graph_database.has_link(
+            link_type=GraphLinkType.MID_TO_NODE,
+            lhs_node=sdoc_node.reserved_mid,
+            rhs_node=sdoc_node,
+        ):
+            traceability_index.graph_database.create_link(
+                link_type=GraphLinkType.MID_TO_NODE,
+                lhs_node=sdoc_node.reserved_mid,
+                rhs_node=sdoc_node,
+            )
+
         for marker_ in source_node.markers:
             if not isinstance(marker_, FunctionRangeMarker):
                 continue