Merge pull request #2523 from strictdoc-project/stanislaw/diff_for_fragments

feat(diff/changelog): support basic change tracking for included documents

Author: stanislaw

docs/strictdoc_04_release_notes.sdoc

@@ -58,6 +58,8 @@ The legacy ``@sdoc`` marker has been removed from the codebase. From now on, onl
 
 An edge case has been fixed where StrictDoc’s FileFinder was detecting Linux pipe files that could not be processed meaningfully by StrictDoc’s source file generator. With this release, such files are now ignored.
 
+The Diff/Changelog feature has been extended to better support change tracking of included documents. Previously, only the contents of included documents were visualized, but not the root nodes of the documents themselves. Now, changes to included documents, such as their UID or TITLE, are displayed correctly.
+
 The ReqIF-to-SDoc converter has been improved to handle integer fields by treating them as string grammar fields. Since StrictDoc does not yet support INTEGER fields, they are converted to STRING fields during import. This workaround was sufficient to support the user’s use case.
 Thanks to @kerfallaCisse for reporting this issue.
 

strictdoc/backend/sdoc/models/model.py

@@ -145,6 +145,9 @@ def iterate_included_documents_depth_first(
     ) -> Generator["SDocDocumentIF", None, None]:
         raise NotImplementedError
 
+    def document_is_included(self) -> bool:
+        raise NotImplementedError
+
     @abstractmethod
     def get_display_title(self, include_toc_number: bool = True) -> str:
         raise NotImplementedError

strictdoc/export/html/templates/screens/git/changelog_content.jinja

@@ -1,11 +1,4 @@
 <div class="changelog_content">
-  {% set documents_modified = view_object.change_container.change_stats.get_changes_documents_modified() %}
-  {% if documents_modified is not none %}
-    {% set _documents_modified = documents_modified %}
-  {% else %}
-    {% set _documents_modified = "No documents were modified." %}
-  {% endif %}
-
   <div class="sdoc-table_key_value">
     {% with key_value_pair =
       {"Section":"Compared revisions"}
@@ -46,6 +39,12 @@
       {% include "components/table_key_value/index.jinja" %}
     {% endwith %}
 
+    {% set documents_modified = view_object.change_container.change_stats.get_changes_documents_modified() %}
+    {% if documents_modified > 0 %}
+        {% set _documents_modified = documents_modified %}
+    {% else %}
+        {% set _documents_modified = "No documents were modified." %}
+    {% endif %}
     {% with key_value_pair =
         {
           "Key":"Documents modified",
@@ -55,6 +54,18 @@
       {% include "components/table_key_value/index.jinja" %}
     {% endwith %}
 
+    {% set documents_included_modified = view_object.change_container.change_stats.get_changes_included_documents_modified() %}
+    {% if documents_included_modified > 0 %}
+        {% with key_value_pair =
+            {
+              "Key":"DOCUMENT (included) nodes",
+              "Value": documents_included_modified,
+            }
+        %}
+          {% include "components/table_key_value/index.jinja" %}
+        {% endwith %}
+    {% endif %}
+
     {% for node_type_ in view_object.get_node_types() %}
       {% set requirements_modified = view_object.change_container.change_stats.get_changes_requirements_changed(node_type_) %}
       {% if requirements_modified is not none %}
@@ -91,12 +102,6 @@
             {% set requirement_change = view_object.change_stats.find_change(requirement) %}
             {% include "screens/git/fields/requirement_fields.jinja" %}
           {% endwith %}
-        {% elif change.change_type == "Section removed" or change.change_type == "Section modified" %}
-          {% assert change.lhs_section is not none, change %}
-          {% with section=change.lhs_section, side="left", self_stats=view_object.change_container.lhs_stats, other_stats=view_object.change_container.rhs_stats, traceability_index=view_object.change_container.traceability_index_lhs %}
-            {% set section_change = view_object.change_stats.find_change(section) %}
-            {% include "screens/git/fields/section_fields.jinja" %}
-          {% endwith %}
         {% elif change.change_type == "Document modified" %}
           {% if change.lhs_document is not none %}
             {% with document=change.lhs_document, side="left", self_stats=view_object.change_container.lhs_stats, other_stats=view_object.change_container.rhs_stats, traceability_index=view_object.change_container.traceability_index_lhs %}
@@ -117,11 +122,6 @@
             {% set requirement_change = view_object.change_stats.find_change(requirement) %}
             {% include "screens/git/fields/requirement_fields.jinja" %}
           {% endwith %}
-        {% elif change.change_type == "Section added" or change.change_type == "Section modified" %}
-          {% with section=change.rhs_section, side="right", self_stats=view_object.change_container.rhs_stats, other_stats=view_object.change_container.lhs_stats, traceability_index=view_object.change_container.traceability_index_rhs %}
-            {% set section_change = view_object.change_stats.find_change(section) %}
-            {% include "screens/git/fields/section_fields.jinja" %}
-          {% endwith %}
         {% elif change.change_type == "Document modified" %}
           {% if change.rhs_document is not none %}
             {% with document=change.rhs_document, side="right", self_stats=view_object.change_container.rhs_stats, other_stats=view_object.change_container.lhs_stats, traceability_index=view_object.change_container.traceability_index_rhs %}

strictdoc/export/html/templates/screens/git/diff_content.jinja

@@ -2,7 +2,7 @@
 {%- if not document_tree_iterator.is_empty_tree() -%}
   <div class="diff_content">
     {%- for folder_or_file in document_tree_iterator.iterator_files_first(): -%}
-      {%- if folder_or_file.is_folder(): %}
+      {%- if folder_or_file.is_folder() %}
         {%- if folder_or_file.files|length > 0 %}
           <div
             class="diff_folder"
@@ -34,14 +34,14 @@
 
             {%- set document_iterator = traceability_index.get_document_iterator(document) -%}
             {%- for section_or_requirement, _ in document_iterator.all_content(print_fragments=True) %}
-              {%- if section_or_requirement.is_requirement() %}
+                {% if section_or_requirement.is_document() %}
+                    {% with document = section_or_requirement %}
+                        {% include "screens/git/node/document.jinja" %}
+                    {% endwith %}
+                {% else %}
                 {%- set requirement = section_or_requirement %}
-                {% include "screens/git/node/requirement.jinja" %}
-
-              {%- elif section_or_requirement.is_document() %}
-                {%- set section = section_or_requirement %}
-                {% include "screens/git/node/section.jinja" %}
-              {%- endif %}
+                    {% include "screens/git/node/requirement.jinja" %}
+                {% endif %}
             {%- endfor -%}
         </details>
         {% endif %}

strictdoc/export/html/templates/screens/git/fields/document_fields.jinja

@@ -27,10 +27,18 @@
     {%- include "components/badge/index.jinja" -%}
   {%- endwith -%}
 
-  {% assert document.reserved_uid is not none %}
-  <div
-    class="sdoc_pre_content"
-  >{{ document.reserved_uid }}</div>
+  {%- if uid_modified -%}
+    {%- set colored_diff = document_change.get_colored_uid_diff(side) -%}
+    {# Using a dummy if block to get rid of leading and trailing whitespaces #}
+    {%- if colored_diff is not none -%}
+      {{ colored_diff }}
+    {%- else -%}
+      {{ document.reserved_uid }}
+    {%- endif -%}
+  {%- else -%}
+    {{ document.reserved_uid }}
+  {%- endif -%}
+
 </div>
 
 {% endif %}

strictdoc/export/html/templates/screens/git/fields/section_fields.jinja

@@ -0,0 +1,29 @@
+{% set document_change = view_object.change_stats.find_change(document) %}
+
+<details
+  class="diff_node"
+  {% if document_change is not none %}
+    modified="{{ side }}"
+  {% endif %}
+>
+  <summary>
+    {%- with badge_text = "DOCUMENT (included)" -%}
+      {%- include "components/badge/index.jinja" -%}
+    {%- endwith -%}
+    <span>
+      {{ document.context.title_number_string if document.context.title_number_string else "&nbsp;"|safe * (document.ng_level * 2 - 1) }}
+    </span>
+    <span>{{ document.reserved_title }}</span>
+    {%- if tab == "diff" -%}
+      {%- if document_change is not none -%}
+        {%- if document_change.document_token is not none -%}
+          {%- with uid=document_change.document_token -%}
+            {%- include "screens/git/sync/button.jinja" -%}
+          {%- endwith -%}
+        {%- endif -%}
+      {%- endif -%}
+    {%- endif -%}
+  </summary>
+
+  {% include "screens/git/fields/document_fields.jinja" %}
+</details>

strictdoc/export/html/templates/screens/git/node/document.jinja

@@ -7,7 +7,12 @@
   {% endif %}
 >
   <summary>
-    {%- with badge_text = "TEXT" if requirement.is_text_node() else "R" -%}
+    {#
+     # FIXME: It would be great to write full node types but CSS must be
+              improved so that a node type is not similar to the node fields
+              visually.
+     #}
+    {%- with badge_text = requirement.node_type[0].upper() -%}
       {%- include "components/badge/index.jinja" -%}
     {%- endwith -%}
     <span>

strictdoc/export/html/templates/screens/git/node/requirement.jinja

@@ -31,22 +31,40 @@ def __init__(
         rhs_document: Optional[SDocDocument],
         uid_modified: bool,
         title_modified: bool,
+        lhs_colored_uid_diff: Optional[Markup],
+        rhs_colored_uid_diff: Optional[Markup],
         lhs_colored_title_diff: Optional[Markup],
         rhs_colored_title_diff: Optional[Markup],
+        document_token: str,
+        is_included_document: bool,
     ):
         assert lhs_document is not None or rhs_document is not None
         if matched_uid is not None:
             assert len(matched_uid) > 0
         self.matched_uid: Optional[str] = matched_uid
         self.uid_modified: bool = uid_modified
         self.title_modified: bool = title_modified
+
+        self.lhs_colored_uid_diff: Optional[Markup] = lhs_colored_uid_diff
+        self.rhs_colored_uid_diff: Optional[Markup] = rhs_colored_uid_diff
+
         self.lhs_colored_title_diff: Optional[Markup] = lhs_colored_title_diff
         self.rhs_colored_title_diff: Optional[Markup] = rhs_colored_title_diff
 
         self.lhs_document: Optional[SDocDocument] = lhs_document
         self.rhs_document: Optional[SDocDocument] = rhs_document
 
         self.change_type: ChangeType = ChangeType.DOCUMENT_MODIFIED
+        self.document_token: str = document_token
+        self.is_included_document: bool = is_included_document
+
+    def get_colored_uid_diff(self, side: str) -> Optional[Markup]:
+        assert self.uid_modified
+        if side == "left":
+            return self.lhs_colored_uid_diff
+        if side == "right":
+            return self.rhs_colored_uid_diff
+        raise AssertionError(f"Must not reach here: {side}")
 
     def get_colored_title_diff(self, side: str) -> Optional[Markup]:
         assert self.title_modified