Merge pull request #401 from melexis/fix-cache

Fix partial rebuild issues

Author: Letme

mlx/traceability/traceability.py

@@ -203,6 +203,9 @@ def perform_consistency_check(app, env):
     for each item ID that matches it and is not defined as a checklist-item.
     """
     env.traceability_collection.process_intermediate_nodes()
+    # Restore implicit reverse relations on every consistency check to handle incremental builds
+    if hasattr(env, 'traceability_collection'):
+        env.traceability_collection.rebuild_implicit_relations()
     ItemRelink.remove_placeholders(env.traceability_collection)
     try:
         env.traceability_collection.self_test(app.config.traceability_notifications.get('undefined-reference'))
@@ -315,8 +318,10 @@ def init_available_relationships(app):
 def initialize_environment(app):
     """Perform initializations needed before the build process starts."""
     env = app.builder.env
-
-    env.traceability_ref_nodes = {}
+    # Preserve cached environment data across incremental builds
+    # Only initialize when missing to avoid losing items/refs from unchanged docs
+    if not hasattr(env, 'traceability_ref_nodes') or env.traceability_ref_nodes is None:
+        env.traceability_ref_nodes = {}
     processed_sort_config = {}
     for attr, sort_spec in app.config.traceability_attributes_sort.items():
         try:
@@ -325,12 +330,22 @@ def initialize_environment(app):
             report_warning(f"Invalid sort configuration for attribute '{attr}': {str(e)}")
             # Fall back to default sorting
             processed_sort_config[attr] = sorted
-    env.traceability_collection = TraceableCollection()
+    if not hasattr(env, 'traceability_collection') or env.traceability_collection is None:
+        env.traceability_collection = TraceableCollection()
+    # Always update sort config on the existing collection
     env.traceability_collection.attributes_sort = processed_sort_config
-    # Copy configuration dictionaries to environment to avoid modifying app.config
-    env.traceability_checklist = dict(app.config.traceability_checklist)
-    env.traceability_attributes = dict(app.config.traceability_attributes)
-    env.traceability_attribute_to_string = dict(app.config.traceability_attribute_to_string)
+    # Copy configuration dictionaries to environment to avoid modifying app.config,
+    # but preserve any cached data (e.g., checklist query_results) on incremental builds
+    if not hasattr(env, 'traceability_checklist') or env.traceability_checklist is None:
+        env.traceability_checklist = dict(app.config.traceability_checklist)
+    else:
+        # Update values from config without dropping existing runtime keys
+        for k, v in app.config.traceability_checklist.items():
+            env.traceability_checklist.setdefault(k, v)
+    if not hasattr(env, 'traceability_attributes') or env.traceability_attributes is None:
+        env.traceability_attributes = dict(app.config.traceability_attributes)
+    if not hasattr(env, 'traceability_attribute_to_string') or env.traceability_attribute_to_string is None:
+        env.traceability_attribute_to_string = dict(app.config.traceability_attribute_to_string)
 
     all_relationships = set(app.config.traceability_relationships).union(app.config.traceability_relationships.values())
     all_relationships.discard('')
@@ -356,6 +371,17 @@ def initialize_environment(app):
     )
 
 
+def _purge(app, env, docname):
+    """Ensure we purge items and relations when a document is updated in incremental builds."""
+    if hasattr(env, 'traceability_collection'):
+        env.traceability_collection.remove_items_from_document(docname)
+    # Purge attribute descriptions defined in this document to avoid stale captions/content
+    to_delete = [attr_id for attr_id, attr in TraceableItem.defined_attributes.items()
+                 if getattr(attr, 'docname', None) == docname]
+    for attr_id in to_delete:
+        del TraceableItem.defined_attributes[attr_id]
+
+
 # ----------------------------------------------------------------------------
 # Event handler helper functions
 def add_checklist_attribute(checklist_config, attributes_config, attribute_to_string_config):
@@ -702,6 +728,7 @@ def copy_html_assets(app, exception):
     app.add_directive('attribute-sort', AttributeSortDirective)
 
     app.connect('builder-inited', initialize_environment)
+    app.connect('env-purge-doc', _purge)
     app.connect('env-check-consistency', perform_consistency_check)
     app.connect('doctree-resolved', process_item_nodes)
 

mlx/traceability/traceable_base_node.py

@@ -64,20 +64,24 @@ def make_internal_item_ref(self, app, item_id):
             break
         item_info = env.traceability_collection.get_item(item_id)
         link_item = item_info
-        notification_item = None
         p_node = nodes.paragraph()
         p_node['classes'].append('item-link')
 
-        # Only create link when target item (or notification item) exists, warn otherwise (in html and terminal)
+        # Early return if target item is missing
+        if item_info is None:
+            p_node.append(nodes.Text(f"{item_id} not defined, broken link"))
+            return p_node
+
+        # If target is a placeholder, try to use the configured notification item; otherwise show broken link
         if item_info.is_placeholder:
             notification_item_id = app.config.traceability_notifications.get('undefined-reference')
             notification_item = env.traceability_collection.get_item(notification_item_id)
-            if not notification_item:
+            if notification_item:
+                link_item = notification_item
+            else:
                 self.has_warned_about_undefined(item_info)
-                txt = nodes.Text('%s not defined, broken link' % item_id)
-                p_node.append(txt)
+                p_node.append(nodes.Text(f"{item_id} not defined, broken link"))
                 return p_node
-            link_item = notification_item
         try:
             if self['document'] == link_item.docname and hasattr(app.builder, 'link_suffix'):
                 # include filename so that the returned node can be reused on every page in the same directory

mlx/traceability/traceable_collection.py

@@ -114,6 +114,25 @@ def has_item(self, itemid):
         '''
         return itemid in self.items
 
+    def remove_items_from_document(self, docname):
+        '''Remove all items that originate from the given document.
+
+        Args:
+            docname (str): Document name (without extension) to purge items for
+        '''
+        to_remove = [identifier for identifier, item in self.items.items()
+                     if getattr(item, 'docname', None) == docname]
+        if not to_remove:
+            return
+        to_remove_set = set(to_remove)
+        # Remove the items themselves
+        for identifier in to_remove:
+            del self.items[identifier]
+        # Remove any relations (explicit and implicit) pointing to the removed items from remaining items
+        for item in self.items.values():
+            for removed_id in to_remove_set:
+                item.remove_targets(removed_id, explicit=True, implicit=True)
+
     def add_relation(self, source_id, relation, target_id):
         '''
         Add relation between two items
@@ -177,6 +196,27 @@ def process_intermediate_nodes(self):
         for node in sorted(self._intermediate_nodes, key=attrgetter('order')):
             node.apply_effect(self)
 
+    def rebuild_implicit_relations(self):
+        """Rebuild all implicit (reverse) relations from explicit ones.
+
+        This is needed on incremental builds when some documents are re-read and others come from cache,
+        so implicit reverse links on re-read items are restored based on the existing explicit links.
+        """
+        # Clear all current implicit relations
+        for item in self.items.values():
+            item.implicit_relations = {}
+
+        # Recreate implicit relations from explicit relations
+        for source_id, source in self.items.items():
+            for relation, targets in source.explicit_relations.items():
+                reverse_relation = self.get_reverse_relation(relation)
+                if not reverse_relation:
+                    continue
+                for target_item in (self.items.get(target_id) for target_id in targets):
+                    if not target_item:
+                        continue
+                    target_item.add_target(reverse_relation, source_id, implicit=True)
+
     def export(self, fname):
         '''
         Exports collection content. The target location of the json file gets created if it doesn't exist yet.