uniword 1.2.5 → 1.3.0

data/lib/uniword/docx/reconciler/referential_integrity.rb

@@ -6,43 +6,21 @@ module Uniword
       # Cross-part referential integrity enforcement.
       #
       # Verifies and repairs references between document.xml and other
-      # package parts. Each method follows the principle of least surprise:
-      # - For removable inline refs (notes): strip dangling silently
-      # - For structural refs (styles, numbering): warn and strip
+      # package parts. Both the allocator (builder) path and the legacy
+      # (template-loaded) path repair by stripping: identical input yields
+      # identical referential outcome regardless of path. Unrepairable
+      # leftovers are rejected by the write-time PackageIntegrityChecker.
+      # - For removable inline refs (notes, hyperlinks, drawings): strip
+      # - For structural refs (styles, numbering): strip
       # - For relationship refs (rId): reconcile against actual parts
+      # - For relationship targets: strip rels whose target part the
+      #   package does not carry (the part is never re-emitted, so the
+      #   rel would dangle in the saved package)
       # - For uniqueness constraints: deduplicate with deterministic resolution
       module ReferentialIntegrity
         def reconcile_referential_integrity
           return unless package.document&.body
 
-          if allocator
-            validate_builder_references
-          else
-            repair_all_references
-          end
-
-          reconcile_style_references
-          reconcile_style_inheritance
-          reconcile_numbering_body_references
-        end
-
-        private
-
-        # Allocator present: builders produce correct output.
-        # Validate builder-constrained references — warn on issues
-        # but don't silently strip (indicates a builder bug).
-        def validate_builder_references
-          validate_note_references(:footnote)
-          validate_note_references(:endnote)
-          reconcile_image_references
-          validate_hyperlink_references
-          ensure_para_id_uniqueness
-          ensure_rid_uniqueness
-          reconcile_sect_pr_references
-        end
-
-        # No allocator: legacy repair path for template-loaded content.
-        def repair_all_references
           reconcile_note_body_references(:footnote)
           reconcile_note_body_references(:endnote)
           reconcile_sect_pr_references
@@ -50,72 +28,14 @@ module Uniword
           reconcile_hyperlink_references
           ensure_para_id_uniqueness
           ensure_rid_uniqueness
-        end
-
-        # Validate that note references in the body match existing notes.
-        # Logs warnings but does NOT strip — builder should produce correct refs.
-        def validate_note_references(type)
-          notes = notes_collection_for(type)
-          return unless notes
-
-          entries = note_entries_for(notes, type)
-          defined_ids = entries
-            .reject { |e| VALID_NOTE_TYPES.include?(e.type) }
-            .filter_map(&:id).to_set
-
-          dangling = 0
-          walk_body_paragraphs(package.document.body) do |para|
-            para.runs.each do |run|
-              ref = note_reference_from_run(run, type)
-              next unless ref&.id
-              next if defined_ids.include?(ref.id)
-
-              dangling += 1
-              Uniword.logger&.warn do
-                "Dangling #{type}note reference id=#{ref.id} in body — " \
-                "builder produced invalid reference"
-              end
-            end
-          end
+          reconcile_relationship_targets
 
-          return unless dangling.positive?
-
-          record_fix(FixCodes::DANGLING_NOTE_REFERENCE_WARNING,
-                     "WARNING: Found #{dangling} dangling #{type}note reference(s) " \
-                     "in body (allocator path — builder bug)")
+          reconcile_style_references
+          reconcile_style_inheritance
+          reconcile_numbering_body_references
         end
 
-        # Validate that hyperlink references match existing rels.
-        # Logs warnings but does NOT strip — builder should register hyperlinks.
-        def validate_hyperlink_references
-          rels = package.document_rels
-          return unless rels
-
-          valid_rids = rels.relationships.to_set(&:id)
-          return if valid_rids.empty?
-
-          dangling = 0
-          walk_body_paragraphs(package.document.body) do |para|
-            (para.hyperlinks || []).each do |hl|
-              next if hl.anchor
-              next unless hl.id
-              next unless hl.id.match?(/\ArId\d+\z/i)
-              next if valid_rids.include?(hl.id)
-
-              dangling += 1
-              Uniword.logger&.warn do
-                "Dangling hyperlink r:id=#{hl.id} in body — " \
-                "builder failed to register hyperlink with allocator"
-              end
-            end
-          end
-
-          return unless dangling.positive?
-
-          record_fix(FixCodes::DANGLING_HYPERLINK_WARNING,
-                     "WARNING: Found #{dangling} dangling hyperlink reference(s) " \
-                     "in body (allocator path — builder bug)")
-        end
+        private
 
         # -- Note references (body → footnotes.xml / endnotes.xml) --
 
@@ -144,17 +64,21 @@ module Uniword
           return unless removed.positive?
 
           record_fix(FixCodes::DANGLING_NOTE_REFERENCE_REMOVED,
-                     "Removed #{removed} dangling #{type}note reference(s) in body")
+                     "Removed #{removed} dangling #{type}note reference(s) in body",
+                     part: "word/document.xml")
         end
 
         # -- Section property references (sectPr → document.xml.rels) --
 
+        # Strip header/footer references whose rId does not resolve.
+        # Builder-registered headers/footers are wired into document_rels
+        # during Group 1 (wire_header_footer_parts), so any reference
+        # still dangling here has no backing part in the unified store.
         def reconcile_sect_pr_references
           sect_pr = package.document&.body&.section_properties
           return unless sect_pr
 
           valid_rids = collect_valid_header_footer_rids
-          return if valid_rids.empty?
 
           removed = 0
           [sect_pr.header_references, sect_pr.footer_references].each do |refs|
@@ -167,14 +91,15 @@ module Uniword
           return unless removed.positive?
 
           record_fix(FixCodes::DANGLING_HEADER_FOOTER_REMOVED,
-                     "Removed #{removed} dangling header/footer reference(s) from sectPr")
+                     "Removed #{removed} dangling header/footer reference(s) from sectPr",
+                     part: "word/document.xml")
         end
 
         def collect_valid_header_footer_rids
           rids = Set.new
 
           (package.document&.header_footer_parts || []).each do |part|
-            rids << part[:r_id] if part[:r_id]
+            rids << part.r_id if part.r_id
           end
 
           collect_rels_by_type(rids,
@@ -212,7 +137,8 @@ module Uniword
           return unless removed.positive?
 
           record_fix(FixCodes::DANGLING_STYLE_REFERENCE_REMOVED,
-                     "Removed #{removed} dangling style reference(s) from body")
+                     "Removed #{removed} dangling style reference(s) from body",
+                     part: "word/document.xml")
         end
 
         # -- Style inheritance (styles.xml self-references) --
@@ -241,7 +167,8 @@ module Uniword
           return unless stripped.positive?
 
           record_fix(FixCodes::DANGLING_BASED_ON_REMOVED,
-                     "Removed #{stripped} dangling basedOn/link reference(s) in styles")
+                     "Removed #{stripped} dangling basedOn/link reference(s) in styles",
+                     part: "word/styles.xml")
         end
 
         # -- Numbering references (body → numbering.xml) --
@@ -271,11 +198,16 @@ module Uniword
           return unless removed.positive?
 
           record_fix(FixCodes::DANGLING_NUMBERING_REMOVED,
-                     "Removed #{removed} dangling numbering reference(s) from body")
+                     "Removed #{removed} dangling numbering reference(s) from body",
+                     part: "word/document.xml")
         end
 
         # -- Image references (blip/@r:embed → document.xml.rels) --
 
+        # Remove drawings whose r:embed has no backing image: either no
+        # matching relationship, or a relationship whose target part the
+        # package does not carry (the rel is R32-stripped below, so both
+        # repairs complete in a single pass regardless of order).
         def reconcile_image_references
           rels = package.document_rels
           return unless rels
@@ -283,28 +215,57 @@ module Uniword
           valid_rids = rels.relationships.to_set(&:id)
           return if valid_rids.empty?
 
-          dangling = 0
+          carried = carried_part_paths
+          targets_by_id = rels.relationships.to_h { |r| [r.id, r.target] }
+          removed = 0
 
           walk_body_paragraphs(package.document.body) do |para|
             (para.runs || []).each do |run|
-              (run.drawings || []).each do |drawing|
-                drawing_embed_rids(drawing).each do |rid|
-                  next if valid_rids.include?(rid)
+              next unless run.drawings
 
-                  dangling += 1
-                end
+              kept = run.drawings.reject do |drawing|
+                dangling_drawing?(drawing, valid_rids, targets_by_id,
+                                  carried)
               end
+              removed += run.drawings.size - kept.size
+              run.drawings = kept
             end
           end
 
-          return unless dangling.positive?
+          return unless removed.positive?
 
           record_fix(FixCodes::DANGLING_DRAWING_REMOVED,
-                     "Found #{dangling} drawing(s) with dangling image reference(s)")
+                     "Removed #{removed} drawing(s) with dangling image reference(s)",
+                     part: "word/document.xml")
+        end
+
+        # A drawing is dangling when it carries embed references and
+        # none of them resolves to a relationship with a carried target.
+        def dangling_drawing?(drawing, valid_rids, targets_by_id, carried)
+          rids = drawing_embed_rids(drawing)
+          return false if rids.empty?
+
+          rids.none? do |rid|
+            valid_rids.include?(rid) &&
+              carried_relationship_target?(targets_by_id[rid], carried)
+          end
+        end
+
+        # A rel target backs the rId only when the package emits it
+        # (External and fragment targets do not need a part).
+        def carried_relationship_target?(target, carried)
+          target = target.to_s
+          return true if target.empty? || target.start_with?("#")
+
+          carried.include?(resolve_relationship_target("word", target))
         end
 
         # -- Hyperlink references (hyperlink/@r:id → document.xml.rels) --
 
+        # Repair hyperlink references: dangling rIds are stripped (like
+        # other referential repairs); literal URLs placed in r:id by
+        # Builder.hyperlink's target= are promoted to proper External
+        # relationships so the package stays valid and the link survives.
         def reconcile_hyperlink_references
           rels = package.document_rels
           return unless rels
@@ -313,23 +274,58 @@ module Uniword
           return if valid_rids.empty?
 
           removed = 0
+          promoted = 0
 
           walk_body_paragraphs(package.document.body) do |para|
             (para.hyperlinks || []).reject! do |hl|
               next false if hl.anchor
               next false unless hl.id
-              next false unless hl.id.match?(/\ArId\d+\z/i)
               next false if valid_rids.include?(hl.id)
 
-              removed += 1
-              true
+              if hl.id.match?(/\ArId\d+\z/i)
+                removed += 1
+                true
+              else
+                promote_literal_hyperlink(rels, hl, valid_rids)
+                promoted += 1
+                false
+              end
             end
           end
 
+          if promoted.positive?
+            record_fix(FixCodes::HYPERLINK_RELATIONSHIP_CREATED,
+                       "Promoted #{promoted} literal hyperlink target(s) " \
+                       "to external relationship(s)",
+                       part: "word/_rels/document.xml.rels")
+          end
+
           return unless removed.positive?
 
           record_fix(FixCodes::DANGLING_HYPERLINK_REMOVED,
-                     "Removed #{removed} dangling hyperlink reference(s) from body")
+                     "Removed #{removed} dangling hyperlink reference(s) from body",
+                     part: "word/document.xml")
+        end
+
+        # Promote a hyperlink whose r:id holds a literal URL to a proper
+        # External relationship, repointing the hyperlink at the new rId.
+        # The rId comes from the allocator (single authority); repeated
+        # literals for the same URL share one relationship.
+        def promote_literal_hyperlink(rels, hyperlink, valid_rids)
+          url = hyperlink.id.to_s
+          rel_type = Ooxml::PartRegistry.find_by_key(:hyperlink).rel_type
+          new_rid = allocator.alloc_rid(target: url, type: rel_type,
+                                        target_mode: "External")
+          unless valid_rids.include?(new_rid)
+            rels.relationships << Ooxml::Relationships::Relationship.new(
+              id: new_rid,
+              type: rel_type,
+              target: url,
+              target_mode: "External",
+            )
+            valid_rids << new_rid
+          end
+          hyperlink.id = new_rid
         end
 
         # -- Uniqueness constraints --
@@ -353,9 +349,15 @@ module Uniword
           return unless collisions.positive?
 
           record_fix(FixCodes::PARAGRAPH_BACKFILL,
-                     "Resolved #{collisions} paraId collision(s)")
+                     "Resolved #{collisions} paraId collision(s)",
+                     part: "word/document.xml")
         end
 
+        # rId uniqueness safety net. With the allocator as single
+        # authority, duplicate rIds are impossible by construction; this
+        # pass only fires on pathological source input (duplicate ids
+        # in the loaded rels). Duplicates are renamed — never
+        # renumbered wholesale — with fresh ids from the allocator.
         def ensure_rid_uniqueness
           rels = package.document_rels
           return unless rels
@@ -375,14 +377,192 @@ module Uniword
 
           return if duplicates.empty?
 
+          rename_duplicate_rids(duplicates)
+
+          record_fix(FixCodes::RELATIONSHIPS_ASSEMBLED,
+                     "Resolved #{duplicates.size} rId collision(s)",
+                     part: "word/_rels/document.xml.rels")
+        end
+
+        # Rename duplicate rels with fresh allocator ids and register
+        # the new bindings so later lookups stay consistent.
+        def rename_duplicate_rids(duplicates)
           duplicates.each do |rel|
             old_id = rel.id
-            rel.id = derive_unique_rid(rels, old_id)
+            rel.id = allocator.register_rid(
+              allocator.next_free_rid,
+              target: rel.target, type: rel.type,
+              target_mode: rel.target_mode
+            )
             record_fix(FixCodes::RELATIONSHIPS_ASSEMBLED,
-                       "Deduplicated rId #{old_id} → #{rel.id}")
+                       "Deduplicated rId #{old_id} → #{rel.id}",
+                       part: "word/_rels/document.xml.rels")
+          end
+        end
+
+        # -- Relationship targets (rels → emitted parts) --
+
+        # Strip relationships whose target part the package does not
+        # carry. Group 3 preserves non-standard source rels verbatim,
+        # including rels to parts uniword does not model (e.g.
+        # docProps/meta.xml); those parts are never re-emitted, so the
+        # rel would dangle (OPC-006) in the saved package.
+        def reconcile_relationship_targets
+          carried = carried_part_paths
+
+          rels_collections.each do |rels, base_dir, part|
+            strip_dangling_relationship_targets(rels, base_dir, carried,
+                                                part)
+          end
+        end
+
+        # [rels, base directory, .rels part path] for every relationships
+        # part the package serializes.
+        def rels_collections
+          [
+            [package.package_rels, "", "_rels/.rels"],
+            [package.document_rels, "word", "word/_rels/document.xml.rels"],
+            [package.settings_rels, "word", "word/_rels/settings.xml.rels"],
+            [package.theme_rels, "word/theme",
+             "word/theme/_rels/theme1.xml.rels"],
+            [package.footnotes_rels, "word", "word/_rels/footnotes.xml.rels"],
+            [package.endnotes_rels, "word", "word/_rels/endnotes.xml.rels"],
+          ]
+        end
+
+        def strip_dangling_relationship_targets(rels, base_dir, carried,
+                                                part)
+          return unless rels&.relationships
+
+          dangling = rels.relationships.select do |rel|
+            dangling_relationship_target?(rel, base_dir, carried)
+          end
+          return if dangling.empty?
+
+          dangling.each { |rel| rels.relationships.delete(rel) }
+          record_target_removal(dangling, part)
+        end
+
+        def record_target_removal(dangling, part)
+          targets = dangling.map { |rel| rel.target.to_s }.join(", ")
+          record_fix(FixCodes::DANGLING_RELATIONSHIP_TARGET_REMOVED,
+                     "Removed #{dangling.size} relationship(s) to parts " \
+                     "not carried by the package: #{targets}",
+                     part: part)
+        end
+
+        # A relationship dangles when it is internal and its resolved
+        # target is not among the parts the save path emits.
+        def dangling_relationship_target?(rel, base_dir, carried)
+          return false if rel.target_mode.to_s == "External"
+
+          target = rel.target.to_s
+          return false if target.empty? || target.start_with?("#")
+
+          !carried.include?(resolve_relationship_target(base_dir, target))
+        end
+
+        # Resolve a relationship target to a normalized package path,
+        # handling package-absolute (leading slash) targets and "..".
+        def resolve_relationship_target(base_dir, target)
+          return target[1..] if target.start_with?("/")
+
+          normalize_package_path(File.join(base_dir, target))
+        end
+
+        # Lexically normalize a package-relative path (resolve "." and
+        # ".." segments). Deliberately avoids File.expand_path, which
+        # prepends a drive letter on Windows.
+        def normalize_package_path(path)
+          segments = []
+          path.split("/").each do |segment|
+            next if segment.empty? || segment == "."
+
+            segment == ".." ? segments.pop : segments << segment
+          end
+          segments.join("/")
+        end
+
+        # Package paths the save path emits, derived from the model —
+        # mirrors serialize_package_parts / inject_* emission.
+        def carried_part_paths
+          paths = carried_word_parts + carried_docprops_parts
+          paths.concat(custom_xml_item_paths)
+          paths.concat(document_part_paths)
+          paths.to_set
+        end
+
+        # [model, package path] pairs for single-instance word/ parts.
+        def carried_word_parts
+          pairs = core_word_pairs + note_word_pairs
+          pairs.filter_map { |model, path| path if model }
+        end
+
+        def core_word_pairs
+          [
+            [package.document, "word/document.xml"],
+            [package.styles, "word/styles.xml"],
+            [package.numbering, "word/numbering.xml"],
+            [package.settings, "word/settings.xml"],
+            [package.font_table, "word/fontTable.xml"],
+            [package.web_settings, "word/webSettings.xml"],
+          ]
+        end
+
+        def note_word_pairs
+          [
+            [package.theme, "word/theme/theme1.xml"],
+            [package.footnotes, "word/footnotes.xml"],
+            [package.endnotes, "word/endnotes.xml"],
+            [package.comments, "word/comments.xml"],
+            [package.document&.bibliography_sources, "word/sources.xml"],
+          ]
+        end
+
+        # [model, package path] pairs for single-instance docProps/ parts.
+        def carried_docprops_parts
+          pairs = [
+            [package.core_properties, "docProps/core.xml"],
+            [package.app_properties, "docProps/app.xml"],
+            [package.custom_properties, "docProps/custom.xml"],
+          ]
+          pairs.filter_map { |model, path| path if model }
+        end
+
+        def custom_xml_item_paths
+          (package.custom_xml_items || []).flat_map do |item|
+            paths = ["customXml/item#{item[:index]}.xml"]
+            if item[:props_xml]
+              paths << "customXml/itemProps#{item[:index]}.xml"
+            end
+            paths
           end
+        end
 
-          record_fix(FixCodes::RELATIONSHIPS_ASSEMBLED, "Resolved #{duplicates.size} rId collision(s)")
+        # Paths emitted from the document model: media, charts,
+        # embeddings, headers and footers (unified part store).
+        def document_part_paths
+          doc = package.document
+          return [] unless doc
+
+          media_chart_paths(doc) + header_footer_paths(doc)
+        end
+
+        def media_chart_paths(doc)
+          paths = [doc.image_parts, doc.chart_parts].compact.flat_map do |parts|
+            parts.values.map { |data| "word/#{data[:target]}" }
+          end
+          paths.concat(embedding_paths)
+        end
+
+        def embedding_paths
+          (package.embeddings || {}).keys.map { |target| "word/#{target}" }
+        end
+
+        def header_footer_paths(doc)
+          doc.header_footer_parts.filter_map do |part|
+            part.target && "word/#{part.target}"
+          end
         end
 
         # -- Traversal helpers --
@@ -437,12 +617,6 @@ module Uniword
             rids << rel.id if type_fragments.any? { |frag| t.include?(frag) }
           end
         end
-
-        def derive_unique_rid(relationships, _current_rel)
-          Ooxml::Relationships::PackageRelationships.next_available_rid(
-            relationships,
-          )
-        end
       end
     end
   end