feat(traceability_index): allow linking nodes via MID

Closes #2552

Author: stanislaw

strictdoc/backend/sdoc/grammar/grammar.py

@@ -80,6 +80,7 @@
   ('ROOT: ' (root = BooleanChoice) '\n')?
   ('OPTIONS:' '\n'
     ('  ENABLE_MID: ' (enable_mid = BooleanChoice) '\n')?
+    ('  RELATION_FIELD: ' (relation_field = SingleLineString) '\n')?
     ('  MARKUP: ' (markup = MarkupChoice) '\n')?
     ('  AUTO_LEVELS: ' (auto_levels = AutoLevelsChoice) '\n')?
     ('  LAYOUT: ' (layout = LayoutChoice) '\n')?

strictdoc/backend/sdoc/models/document_config.py

@@ -50,6 +50,7 @@ def default_config(document: Optional["SDocDocument"]) -> "DocumentConfig":
             requirement_prefix=None,
             root=None,
             enable_mid=None,
+            relation_field=None,
             markup=None,
             auto_levels=None,
             layout=None,
@@ -70,6 +71,7 @@ def __init__(
         requirement_prefix: Optional[str],
         root: Optional[str],
         enable_mid: Optional[str],
+        relation_field: Optional[str],
         markup: Optional[str],
         auto_levels: Optional[str],
         layout: Optional[str],
@@ -100,6 +102,11 @@ def __init__(
             if enable_mid == "True"
             else (False if root == "False" else None)
         )
+        self.relation_field: str = (
+            relation_field
+            if relation_field is not None and len(relation_field) > 0
+            else "UID"
+        )
 
         self.markup: Optional[str] = markup
         self.auto_levels: bool = auto_levels is None or auto_levels == "On"

strictdoc/backend/sdoc/models/node.py

@@ -7,6 +7,7 @@
 
 from strictdoc.backend.sdoc.document_reference import DocumentReference
 from strictdoc.backend.sdoc.models.anchor import Anchor
+from strictdoc.backend.sdoc.models.document_config import DocumentConfig
 from strictdoc.backend.sdoc.models.document_grammar import (
     DocumentGrammar,
 )
@@ -305,14 +306,20 @@ def has_any_text_nodes(self) -> bool:
 
     @property
     def reserved_uid(self) -> Optional[str]:
+        document = assert_cast(self.get_document(), SDocDocumentIF)
+        config = assert_cast(document.config, DocumentConfig)
+
         return self._get_cached_field(
-            RequirementFieldName.UID, singleline_only=True
+            config.relation_field, singleline_only=True
         )
 
     @reserved_uid.setter
     def reserved_uid(self, uid: Optional[str]) -> None:
+        document = assert_cast(self.get_document(), SDocDocumentIF)
+        config = assert_cast(document.config, DocumentConfig)
+
         self.set_field_value(
-            field_name="UID",
+            field_name=config.relation_field,
             form_field_index=0,
             value=uid,
         )
@@ -407,8 +414,8 @@ def get_debug_info(self) -> str:
         debug_components: List[str] = []
         if self.reserved_mid is not None:
             debug_components.append(f"MID = '{self.reserved_mid}'")
-        if self.reserved_uid is not None:
-            debug_components.append(f"UID = '{self.reserved_uid}'")
+        if (reserved_uid_ := self.reserved_uid) is not None:
+            debug_components.append(f"UID = '{reserved_uid_}'")
         if self.reserved_title is not None:
             debug_components.append(f"TITLE = '{self.reserved_title}'")
 

strictdoc/core/file_traceability_index.py

@@ -456,7 +456,6 @@ def validate_and_resolve(
                         reqs_uids,
                     )
 
-            validated_requirement_uids: Set[str] = set()
             marker_: Union[
                 FunctionRangeMarker, LineMarker, RangeMarker, ForwardRangeMarker
             ]
@@ -465,29 +464,23 @@ def validate_and_resolve(
                 if isinstance(marker_, ForwardRangeMarker):
                     continue
                 for requirement_uid_ in marker_.reqs:
-                    if requirement_uid_ not in validated_requirement_uids:
-                        node = traceability_index.get_node_by_uid_weak2(
-                            requirement_uid_
+                    node = traceability_index.get_node_by_uid_weak2(
+                        requirement_uid_
+                    )
+                    if node is None:
+                        raise StrictDocException(
+                            f"Source file {source_file.in_doctree_source_file_rel_path_posix} references "
+                            f"a requirement that does not exist: {requirement_uid_}."
                         )
-                        if node is None:
-                            raise StrictDocException(
-                                f"Source file {source_file.in_doctree_source_file_rel_path_posix} references "
-                                f"a requirement that does not exist: {requirement_uid_}."
-                            )
-                        validated_requirement_uids.add(requirement_uid_)
 
                     self.map_reqs_uids_to_paths.setdefault(
                         requirement_uid_, OrderedSet()
                     ).add(source_file.in_doctree_source_file_rel_path_posix)
 
-                    node_id = traceability_index.get_node_by_uid(
-                        requirement_uid_
-                    )
-
                     self.map_paths_to_reqs.setdefault(
                         source_file.in_doctree_source_file_rel_path_posix,
                         OrderedSet(),
-                    ).add(node_id)
+                    ).add(node)
 
                 if isinstance(marker_, FunctionRangeMarker):
                     marker_copy = marker_.create_end_marker()

tests/integration/features/sdoc/RELATION_FIELD/01_mid_based_relation/input.sdoc

@@ -0,0 +1,18 @@
+[DOCUMENT]
+TITLE: Test document
+OPTIONS:
+  ENABLE_MID: True
+  RELATION_FIELD: MID
+
+[REQUIREMENT]
+MID: aaaaaaaa_aaaaaaaa_aaaaaaaa_aaaaaaaa
+TITLE: Requirement A title
+STATEMENT: Requirement A statement
+
+[REQUIREMENT]
+MID: bbbbbbbb_bbbbbbbb_bbbbbbbb_bbbbbbbb
+TITLE: Requirement B title
+STATEMENT: Requirement B statement
+RELATIONS:
+- TYPE: Parent
+  VALUE: aaaaaaaa_aaaaaaaa_aaaaaaaa_aaaaaaaa

tests/integration/features/sdoc/RELATION_FIELD/01_mid_based_relation/test.itest

@@ -0,0 +1,12 @@
+RUN: %strictdoc export %S --output-dir %T | filecheck %s
+CHECK: Published: Test document
+
+RUN: %cat %T/html/%THIS_TEST_FOLDER/input.html | filecheck %s --check-prefix CHECK-HTML
+
+CHECK-HTML: RELATIONS (Child):
+CHECK-HTML: <a data-turbo="false" class="requirement__link-child" href="#bbbbbbbb_bbbbbbbb_bbbbbbbb_bbbbbbbb">
+CHECK-HTML: Requirement B title
+
+CHECK-HTML: RELATIONS (Parent):
+CHECK-HTML: <a data-turbo="false" class="requirement__link-parent" href="#aaaaaaaa_aaaaaaaa_aaaaaaaa_aaaaaaaa">
+CHECK-HTML: Requirement A title

tests/integration/features/source_code_traceability/_RELATION_FIELD/file.py

@@ -0,0 +1,16 @@
+def hello_world():
+    """
+    Some text.
+
+    @relation(REQ-1, scope=function)
+    """
+    # @relation(REQ-1, scope=range_start)
+    print("hello world")  # noqa: T201
+    # @relation(REQ-1, scope=range_end)
+    print("hello world")  # noqa: T201
+    # @relation(REQ-1, scope=range_start)
+    print("hello world")  # noqa: T201
+    # @relation(REQ-1, scope=range_end)
+
+def non_covered_function():
+    pass

tests/integration/features/source_code_traceability/_RELATION_FIELD/input.sdoc

@@ -0,0 +1,10 @@
+[DOCUMENT]
+TITLE: Hello world doc
+OPTIONS:
+  ENABLE_MID: True
+  RELATION_FIELD: MID
+
+[REQUIREMENT]
+MID: REQ-1
+TITLE: Requirement Title
+STATEMENT: Requirement Statement

tests/integration/features/source_code_traceability/_RELATION_FIELD/strictdoc.toml

@@ -0,0 +1,10 @@
+[project]
+
+features = [
+  "REQUIREMENT_TO_SOURCE_TRACEABILITY",
+  "SOURCE_FILE_LANGUAGE_PARSERS",
+]
+
+exclude_source_paths = [
+  "test.itest",
+]

tests/integration/features/source_code_traceability/_RELATION_FIELD/test.itest

@@ -0,0 +1,19 @@
+# @relation(SDOC-SRS-147, SDOC-SRS-137, scope=file)
+
+RUN: %strictdoc --debug export %S --output-dir %T | filecheck %s --dump-input=fail
+CHECK: Published: Hello world doc
+
+RUN: %check_exists --file "%T/html/_source_files/file.py.html"
+
+RUN: %cat %T/html/%THIS_TEST_FOLDER/input.html | filecheck %s --check-prefix CHECK-HTML
+CHECK-HTML: <a{{.*}}href="../_source_files/file.py.html#REQ-1#1#13">
+CHECK-HTML: <a{{.*}}href="../_source_files/file.py.html#REQ-1#7#9">
+CHECK-HTML: <a{{.*}}href="../_source_files/file.py.html#REQ-1#11#13">
+
+RUN: %cat %T/html/_source_files/file.py.html | filecheck %s --check-prefix CHECK-SOURCE-FILE
+CHECK-SOURCE-FILE: 1 - 13 | function hello_world()
+CHECK-SOURCE-FILE: 7 - 9 | range
+CHECK-SOURCE-FILE: 11 - 13 | range
+
+RUN: %cat %T/html/source_coverage.html | filecheck %s --dump-input=fail --check-prefix CHECK-SOURCE-COVERAGE
+CHECK-SOURCE-COVERAGE: 85.7