uniword 1.0.11 → 1.2.4

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

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class Reconciler
+      # Footnote and endnote reconciliation.
+      #
+      # Ensures notes are structurally valid with separators, proper ordering
+      # and sequential IDs. Creates missing notes/settings pairs and strips
+      # invalid types.
+      module Notes
+        def reconcile_note_references
+          [:footnote, :endnote].each do |type|
+            ref_ids = collect_note_ids(type)
+            next if ref_ids.empty?
+
+            current = notes_collection_for(type)
+
+            if current.nil?
+              ensure_notes_part(type)
+              current = notes_collection_for(type)
+            end
+
+            defined_set = note_entries_for(current, type).map(&:id).to_set
+
+            missing = ref_ids.reject { |id| defined_set.include?(id) }
+            next if missing.empty?
+
+            entries = note_entries_for(current, type)
+            missing.each do |id|
+              entries << entry_class(type).new(
+                id: id,
+                paragraphs: [Wordprocessingml::Paragraph.new(
+                  runs: [Wordprocessingml::Run.new(
+                    text: Wordprocessingml::Text.new(content: " ")
+                  )]
+                )],
+              )
+            end
+            record_fix(FixCodes::NOTE_DEFINITION_CREATED,
+                       "Created missing #{type}note definitions for ids=#{missing.join(', ')}")
+          end
+        end
+
+        def reconcile_footnotes
+          reconcile_notes_type(
+            notes: package.footnotes,
+            notes_setter: ->(v) { package.footnotes = v },
+            has_pr: package.settings&.footnote_pr,
+            type: :footnote,
+            create_message: "Created footnotes.xml to match footnotePr in settings",
+            pr_message: "Added footnotePr to settings to match footnotes.xml",
+          )
+        end
+
+        def reconcile_endnotes
+          reconcile_notes_type(
+            notes: package.endnotes,
+            notes_setter: ->(v) { package.endnotes = v },
+            has_pr: package.settings&.endnote_pr,
+            type: :endnote,
+            create_message: "Created endnotes.xml to match endnotePr in settings",
+            pr_message: "Added endnotePr to settings to match endnotes.xml",
+          )
+        end
+
+        private
+
+        def reconcile_notes_type(notes:, notes_setter:, has_pr:, type:,
+                                 create_message:, pr_message:)
+          if has_pr && !notes
+            notes_setter.call(minimal_notes(type))
+            record_fix(FixCodes::NOTE_PAIR_CREATED, create_message)
+          elsif notes && !has_pr
+            package.settings ||= Wordprocessingml::Settings.new
+            assign_note_pr(package.settings, type)
+            record_fix(FixCodes::NOTE_PAIR_CREATED, pr_message)
+          end
+
+          current = notes_collection_for(type)
+          return unless current
+
+          entries = note_entries_for(current, type)
+
+          finalize_notes(current, entries, type)
+        end
+
+        def finalize_notes(notes, entries, type)
+          ensure_separators(notes, type, entries)
+          strip_invalid_note_types(entries, type)
+          deduplicate_note_ids(entries, type)
+          strip_empty_runs_from_notes(entries)
+          reorder_notes_by_reference(entries, type)
+
+          unless allocator
+            prefix = type == :footnote ? "fn" : "en"
+
+            entries.each_with_index do |entry, eidx|
+              backfill_paragraphs(entry.paragraphs, generate_rsid,
+                                  "#{prefix}:#{eidx}")
+            end
+
+            renumber_notes(entries, type)
+          end
+
+          set_mc_ignorable(notes, prefixes: FULL_IGNORABLE)
+        end
+
+        def minimal_notes(type)
+          entries = [separator_entry(type), continuation_entry(type)]
+          build_notes_collection(type, entries: entries)
+        end
+
+        def entry_class(type)
+          type == :footnote ? Wordprocessingml::Footnote : Wordprocessingml::Endnote
+        end
+
+        def separator_entry(type)
+          entry_class(type).new(
+            id: "-1", type: "separator",
+            paragraphs: [separator_paragraph(:separator)]
+          )
+        end
+
+        def continuation_entry(type)
+          entry_class(type).new(
+            id: "0", type: "continuationSeparator",
+            paragraphs: [separator_paragraph(:continuation)]
+          )
+        end
+
+        def separator_paragraph(kind = :separator)
+          sep_attr = kind == :separator ? :separator_char : :continuation_separator_char
+          sep_class = kind == :separator ? Wordprocessingml::SeparatorChar : Wordprocessingml::ContinuationSeparatorChar
+          sep_run = Wordprocessingml::Run.new(sep_attr => sep_class.new)
+          Wordprocessingml::Paragraph.new(
+            properties: Wordprocessingml::ParagraphProperties.new(
+              spacing: Properties::Spacing.new(after: 0, line: 240,
+                                               line_rule: "auto"),
+            ),
+            runs: [sep_run]
+          )
+        end
+
+        def ensure_separators(notes, type, entries)
+          entries.each do |entry|
+            next unless %w[separator continuationSeparator].include?(entry.type)
+            next if entry.paragraphs.empty?
+
+            entry.paragraphs.each do |p|
+              strip_empty_runs(p)
+              ensure_separator_run(p, entry.type)
+            end
+          end
+
+          ids = entries.to_set(&:id)
+          entries.unshift(separator_entry(type)) unless ids.include?("-1")
+          entries.unshift(continuation_entry(type)) unless ids.include?("0")
+        end
+
+        def ensure_separator_run(para, type)
+          has_sep = para.runs.any? { |r| r.separator_char || r.continuation_separator_char }
+          return if has_sep
+
+          sep = if type == "separator"
+                  Wordprocessingml::Run.new(separator_char: Wordprocessingml::SeparatorChar.new)
+                else
+                  Wordprocessingml::Run.new(continuation_separator_char: Wordprocessingml::ContinuationSeparatorChar.new)
+                end
+          para.runs << sep
+        end
+
+        def strip_invalid_note_types(entries, type)
+          stripped = []
+          entries.each do |entry|
+            next if VALID_NOTE_TYPES.include?(entry.type)
+            next unless entry.type
+
+            stripped << entry.id
+            entry.type = nil
+          end
+          return if stripped.empty?
+
+          record_fix(FixCodes::NOTE_INVALID_TYPE_STRIPPED,
+                     "Stripped invalid w:type from #{type}note ids=#{stripped.join(', ')}")
+        end
+
+        def deduplicate_note_ids(entries, type)
+          seen = {}
+          dup_ids = []
+          entries.reject! do |entry|
+            if seen[entry.id]
+              dup_ids << entry.id
+              true
+            else
+              seen[entry.id] = true
+              false
+            end
+          end
+          return if dup_ids.empty?
+
+          record_fix(FixCodes::NOTE_DUPLICATE_ID_REMOVED,
+                     "Removed duplicate #{type}note ids=#{dup_ids.join(', ')}")
+        end
+
+        def reorder_notes_by_reference(entries, type)
+          body = package.document&.body
+          return unless body
+
+          ref_order = collect_note_reference_order(body, type)
+          return if ref_order.empty?
+
+          structural = entries.select { |e| VALID_NOTE_TYPES.include?(e.type) }
+          user_entries = entries.reject { |e| VALID_NOTE_TYPES.include?(e.type) }
+          return if user_entries.size <= 1
+
+          by_id = user_entries.group_by(&:id)
+          reordered = ref_order.filter_map { |id| by_id[id]&.first }
+
+          referenced_ids = ref_order.to_set
+          unreferenced = user_entries.reject { |e| referenced_ids.include?(e.id) }
+          reordered.concat(unreferenced)
+
+          return if reordered == user_entries
+
+          entries.clear
+          structural.each { |e| entries << e }
+          reordered.each { |e| entries << e }
+
+          record_fix(FixCodes::NOTE_PAIR_CREATED, "Reordered #{type}notes by first reference in document body")
+        end
+
+        def renumber_notes(entries, type)
+          user_entries = entries.reject { |e| VALID_NOTE_TYPES.include?(e.type) }
+          return if user_entries.size <= 1
+
+          id_map = {}
+          user_entries.each_with_index do |entry, idx|
+            old_id = entry.id
+            new_id = (idx + 1).to_s
+            next if old_id == new_id
+            id_map[old_id] = new_id
+            entry.id = new_id
+          end
+          return if id_map.empty?
+
+          body = package.document&.body
+          return unless body
+
+          walk_body_paragraphs(body) do |para|
+            para.runs.each do |run|
+              ref = note_reference_from_run(run, type)
+              next unless ref && ref.id && id_map.key?(ref.id)
+              ref.id = id_map[ref.id]
+            end
+          end
+
+          record_fix(FixCodes::NOTE_PAIR_CREATED, "Renumbered #{type}note IDs sequentially (#{id_map.size} changed)")
+        end
+
+        def collect_note_reference_order(body, type)
+          seen = []
+
+          walk_body_paragraphs(body) do |para|
+            para.runs.each do |run|
+              ref = note_reference_from_run(run, type)
+              next unless ref && ref.id
+              seen << ref.id unless seen.include?(ref.id)
+            end
+          end
+
+          seen
+        end
+
+        # note_reference_from_run lives in Helpers (single source for note-type dispatch).
+
+        def collect_note_ids(type)
+          ids = []
+          body = package.document&.body
+          return ids unless body
+
+          walk_body_paragraphs(body) do |para|
+            para.runs.each do |run|
+              ref = note_reference_from_run(run, type)
+              ids << ref.id if ref&.id
+            end
+          end
+          ids
+        end
+
+        def ensure_notes_part(type)
+          notes = build_notes_collection(
+            type,
+            entries: [separator_entry(type), continuation_entry(type)],
+          )
+          set_notes_collection(notes, type)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    class Reconciler
+      # Package-level consistency enforcement.
+      #
+      # Rebuilds content types and relationships for standard parts,
+      # preserving non-standard entries from the source document.
+      module PackageStructure
+        # Relationship types for parts we don't model or serialize.
+        UNSUPPORTED_REL_TYPES = Set[
+          "http://schemas.microsoft.com/office/2007/relationships/stylesWithEffects",
+        ].freeze
+
+        # Rel types that belong in package-level _rels/.rels, not document.xml.rels.
+        PACKAGE_LEVEL_REL_TYPES = Set[
+          "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument",
+          "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties",
+          "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties",
+          "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties",
+        ].freeze
+
+        def reconcile_content_types
+          ct = package.content_types
+          return unless ct
+
+          ct.defaults = [
+            Uniword::ContentTypes::Default.new(
+              extension: "rels",
+              content_type: "application/vnd.openxmlformats-package.relationships+xml",
+            ),
+            Uniword::ContentTypes::Default.new(
+              extension: "xml",
+              content_type: "application/xml",
+            ),
+          ]
+
+          standard = content_type_overrides_for_present_parts
+          standard_parts = standard.to_set(&:part_name)
+          non_standard = ct.overrides.reject do |o|
+            standard_parts.include?(o.part_name)
+          end
+
+          ct.overrides = standard + non_standard
+          record_fix(FixCodes::CONTENT_TYPES_ASSEMBLED, "Rebuilt content types for standard parts")
+        end
+
+        def reconcile_package_rels
+          rels = package.package_rels
+          return unless rels
+
+          base = "http://schemas.openxmlformats.org"
+          standard_defs = [
+            ["rId1",
+             "#{base}/officeDocument/2006/relationships/officeDocument",
+             "word/document.xml"],
+            ["rId2",
+             "#{base}/package/2006/relationships/metadata/core-properties",
+             "docProps/core.xml"],
+            ["rId3",
+             "#{base}/officeDocument/2006/relationships/extended-properties",
+             "docProps/app.xml"],
+          ]
+
+          standard_targets = standard_defs.to_set { |_, _, t| t }
+          standard_rids = standard_defs.to_set { |rid, _, _| rid }
+          non_standard = rels.relationships.reject do |r|
+            standard_targets.include?(r.target) || standard_rids.include?(r.id)
+          end
+
+          existing_by_target = rels.relationships.to_h { |r| [r.target, r] }
+          standard = standard_defs.map do |rid, type, target|
+            existing = existing_by_target[target]
+            build_rel(existing ? existing.id : rid, type, target)
+          end
+
+          rels.relationships = standard + non_standard
+          record_fix(FixCodes::RELATIONSHIPS_ASSEMBLED, "Rebuilt package relationships for standard parts")
+        end
+
+        def reconcile_document_rels
+          rels = package.document_rels
+          return unless rels
+
+          base = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+          defs = [
+            ["styles", "styles.xml", package.styles],
+            ["settings", "settings.xml", package.settings],
+            ["webSettings", "webSettings.xml", package.web_settings],
+            ["fontTable", "fontTable.xml", package.font_table],
+            ["theme", "theme/theme1.xml", package.theme],
+            ["numbering", "numbering.xml", package.numbering],
+            ["footnotes", "footnotes.xml", package.footnotes],
+            ["endnotes", "endnotes.xml", package.endnotes],
+          ]
+
+          standard_targets = defs.filter_map { |_, target, obj| target if obj }.to_set
+
+          # If allocator is present, use it to build rels — preserves existing rIds
+          alloc = allocator
+          if alloc
+            reconcile_document_rels_from_allocator(rels, base, defs, standard_targets, alloc)
+          else
+            reconcile_document_rels_legacy(rels, base, defs, standard_targets)
+          end
+        end
+
+        private
+
+        def reconcile_document_rels_from_allocator(rels, base, defs, standard_targets, alloc)
+          # Collect standard part rels from allocator
+          all_rels = []
+          defs.each do |suffix, target, obj|
+            next unless obj
+            r_id = alloc.rid_for(target: target, type: "#{base}/#{suffix}")
+            if r_id
+              all_rels << build_rel(r_id, "#{base}/#{suffix}", target)
+            else
+              all_rels << build_rel(
+                alloc.alloc_rid(target: target, type: "#{base}/#{suffix}"),
+                "#{base}/#{suffix}", target,
+              )
+            end
+          end
+
+          # Add allocator-managed rels (images, headers, footers, hyperlinks)
+          alloc.all_rels.each do |entry|
+            next if standard_targets.include?(entry[:target])
+            next if all_rels.any? { |r| r.target == entry[:target] }
+            next if unsupported_rel_type?(entry[:type])
+            next if package_level_rel?(entry[:type])
+            next unless header_footer_target_present?(entry[:target])
+
+            all_rels << build_rel(
+              entry[:id], entry[:type], entry[:target],
+              target_mode: entry[:target_mode],
+            )
+          end
+
+          # Preserve non-standard rels not managed by allocator
+          existing_targets = all_rels.to_set(&:target)
+          non_standard = rels.relationships.reject do |r|
+            existing_targets.include?(r.target) ||
+              standard_targets.include?(r.target) ||
+              unsupported_rel_type?(r.type) ||
+              package_level_rel?(r.type) ||
+              !header_footer_target_present?(r.target)
+          end
+
+          rels.relationships = all_rels + non_standard
+          record_fix(FixCodes::RELATIONSHIPS_ASSEMBLED, "Assembled document relationships from allocator")
+        end
+
+        def reconcile_document_rels_legacy(rels, base, defs, standard_targets)
+          non_standard = rels.relationships.reject do |r|
+            standard_targets.include?(r.target) ||
+              unsupported_rel_type?(r.type) ||
+              package_level_rel?(r.type) ||
+              !header_footer_target_present?(r.target)
+          end
+
+          all_rels = []
+          rid_mapping = {}
+
+          defs.each do |suffix, target, obj|
+            next unless obj
+            rid = "rId#{all_rels.size + 1}"
+            all_rels << build_rel(rid, "#{base}/#{suffix}", target)
+          end
+
+          non_standard.each do |rel|
+            old_rid = rel.id
+            new_rid = "rId#{all_rels.size + 1}"
+            rid_mapping[old_rid] = new_rid if old_rid != new_rid
+            all_rels << build_rel(new_rid, rel.type, rel.target,
+                                  target_mode: rel.target_mode)
+          end
+
+          rels.relationships = all_rels
+          update_sect_pr_rid_references(rid_mapping) unless rid_mapping.empty?
+          update_blip_embed_references(rid_mapping) unless rid_mapping.empty?
+          update_hyperlink_rid_references(rid_mapping) unless rid_mapping.empty?
+          record_fix(FixCodes::RELATIONSHIPS_ASSEMBLED, "Rebuilt document relationships with sequential rIds")
+        end
+
+        def update_sect_pr_rid_references(mapping)
+          sect_pr = package.document&.body&.section_properties
+          return unless sect_pr
+
+          [sect_pr.header_references, sect_pr.footer_references].each do |refs|
+            next unless refs
+
+            refs.each do |ref|
+              new_rid = mapping[ref.r_id]
+              ref.r_id = new_rid if new_rid
+            end
+          end
+        end
+
+        def update_blip_embed_references(mapping)
+          paragraphs = package.document&.body&.paragraphs
+          return unless paragraphs
+
+          paragraphs.each do |para|
+            next unless para.runs
+
+            para.runs.each do |run|
+              next unless run.drawings
+
+              run.drawings.each do |drawing|
+                update_drawing_blip(drawing, mapping)
+              end
+            end
+          end
+        end
+
+        def update_drawing_blip(drawing, mapping)
+          graphic = drawing.inline&.graphic || drawing.anchor&.graphic
+          return unless graphic
+
+          picture = graphic.graphic_data&.picture
+          return unless picture
+
+          blip = picture.blip_fill&.blip
+          return unless blip&.embed
+
+          new_rid = mapping[blip.embed.to_s]
+          blip.embed = new_rid if new_rid
+        end
+
+        def update_hyperlink_rid_references(mapping)
+          body = package.document&.body
+          return unless body
+
+          walk_body_paragraphs(body) do |para|
+            (para.hyperlinks || []).each do |hl|
+              next unless hl.id
+              new_rid = mapping[hl.id.to_s]
+              hl.id = new_rid if new_rid
+            end
+          end
+        end
+
+        def unsupported_rel_type?(type)
+          UNSUPPORTED_REL_TYPES.include?(type.to_s)
+        end
+
+        def package_level_rel?(type)
+          PACKAGE_LEVEL_REL_TYPES.include?(type.to_s)
+        end
+
+        # Check if a header/footer rel target corresponds to a serialized part.
+        # Headers/footers may be in two places:
+        #   - document.headers / document.footers (single-section hash)
+        #   - document.header_footer_parts (multi-section ordered array)
+        # Headers/footers are numbered sequentially: header1.xml, header2.xml...
+        # If the model has fewer headers/footers than the target index, it's stale.
+        def header_footer_target_present?(target)
+          if target.start_with?("header") && target.end_with?(".xml")
+            num = target[/header(\d+)\.xml/, 1]&.to_i
+            hash_count = package.document&.headers&.size || 0
+            parts_count = count_parts_matching("header")
+            count = [hash_count, parts_count].max
+            return num && num <= count
+          end
+          if target.start_with?("footer") && target.end_with?(".xml")
+            num = target[/footer(\d+)\.xml/, 1]&.to_i
+            hash_count = package.document&.footers&.size || 0
+            parts_count = count_parts_matching("footer")
+            count = [hash_count, parts_count].max
+            return num && num <= count
+          end
+          true
+        end
+
+        def count_parts_matching(prefix)
+          parts = package.document&.header_footer_parts
+          return 0 unless parts
+
+          parts.count { |p| p[:target].to_s.start_with?(prefix) }
+        end
+
+        def content_type_overrides_for_present_parts
+          checks = [
+            [package.document, "/word/document.xml",
+             "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"],
+            [package.styles, "/word/styles.xml",
+             "application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"],
+            [package.settings, "/word/settings.xml",
+             "application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml"],
+            [package.font_table, "/word/fontTable.xml",
+             "application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml"],
+            [package.web_settings, "/word/webSettings.xml",
+             "application/vnd.openxmlformats-officedocument.wordprocessingml.webSettings+xml"],
+            [package.theme, "/word/theme/theme1.xml",
+             "application/vnd.openxmlformats-officedocument.theme+xml"],
+            [package.core_properties, "/docProps/core.xml",
+             "application/vnd.openxmlformats-package.core-properties+xml"],
+            [package.app_properties, "/docProps/app.xml",
+             "application/vnd.openxmlformats-officedocument.extended-properties+xml"],
+            [package.footnotes, "/word/footnotes.xml",
+             "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml"],
+            [package.endnotes, "/word/endnotes.xml",
+             "application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml"],
+            [package.numbering, "/word/numbering.xml",
+             "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"],
+          ]
+
+          checks.filter_map do |obj, part_name, content_type|
+            next unless obj
+
+            Uniword::ContentTypes::Override.new(
+              part_name: part_name,
+              content_type: content_type,
+            )
+          end
+        end
+      end
+    end
+  end
+end