uniword 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e697ff947a11616fb287bf07ce59d09216921223355b7e9315d81947a48e1bc4
-  data.tar.gz: 10999851891264d1f1f75d8cb74d06966d790c5f464a82cf9c168fffddb57666
+  metadata.gz: b6093ee22688fc357250708811cdb7035b17ff9a036ec5dd48f86381632b2c72
+  data.tar.gz: b76ab89a27b22a8a7ed5293f771cedaa165c3263a853f3322eb9f3d06cd0625a
 SHA512:
-  metadata.gz: 4043eba31c5334bc6b4770cd10e51dc3491a4ae76ee5f286e35131e415ee284f392c55aaa521980972973f511a29191c6eb2cf58fbea47d6e52aae0fd8140890
-  data.tar.gz: fc8c60a46ee435a07f26c536991863e8bfc0ba9f16e6f4ba95c24c27e0ad65a1078cc455fc78f336e65f9fb54bf89356b0071ecdb8a28ca0842f8d92b46706c8
+  metadata.gz: dedfcb861076ff92eb99dda31c460e02a4c184fd9ce271abdfc63250dd100235f0889e4705899d2f4566eefa43b329094d77128f9ff9deeae3ff635ca4051218
+  data.tar.gz: 226c5d1acc52df7f5519935ab2817b73ac71382fb95132e66cd6bfc4f1d912dba604996d0e1eff9996791f0bf0a38df121d27d54e5a012c1236d582580f93484

data/CHANGELOG.md

@@ -8,6 +8,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-07-22
+
+### Added
+
+- `Configuration#on_noncompliant_content` policy knob (default
+  `:strip`, alternative `:raise`). Controls what happens when a
+  loaded package contains parts with no content type declaration.
+- `Docx::JunkClassifier` — classifies a package-relative path as
+  junk based on OS/tooling artifact patterns and the OPC "no content
+  type AND no referencing relationship" rule. Single source of truth
+  for the junk decision.
+- `Docx::StrippedPart` value object (path + reason) — the reporting
+  record for parts stripped at load.
+- `ContentTypes::Types#content_type_for(path)` — Override-then-Default
+  lookup. Single source of truth for content type resolution,
+  replacing duplicated lookup logic.
+- `Package#stripped_parts` — `Array<StrippedPart>` populated by the
+  loader in `:strip` mode. Empty in `:raise` mode and for
+  programmatically-constructed packages.
+
+### Changed
+
+- **Default behavior change**: `Docx::RawPartLoader` now strips
+  non-compliant parts at load by default (Word-identical behavior).
+  Previously, parts with no content type declaration were preserved
+  as `RawPart(content_type: nil)`, which then tripped OPC-005 at the
+  write-time integrity gate. Legitimate unmodelled parts (those with
+  a content type declaration, e.g. VBA, glossary, `docProps/meta.xml`)
+  continue to round-trip byte-for-byte per the 1.4.0 promise.
+- Stripped parts are recorded on `Package#stripped_parts` for caller
+  introspection. Set `Configuration#on_noncompliant_content = :raise`
+  to preserve the previous behavior for QA pipelines that want to
+  catch every deviation.
+
+### Fixed
+
+- Loading then saving a DOCX with `[trash]/*.dat` or other
+  undeclared parts no longer fails with
+  `OPC-005 No content type declared` at save. The junk is stripped
+  at load and reported via `Package#stripped_parts`.
+
+### Removed
+
+- `FALLBACK_RAW_PART_CONTENT_TYPE` constant and the
+  `application/octet-stream` fallback in
+  `Docx::PackageSerialization#inject_raw_part_content_types`. The
+  fallback preserved junk that Word would strip and masked genuinely
+  missing declarations. (Introduced in 1.4.1; reverted before
+  broader release.)
+
 ## [1.4.0] - 2026-07-20
 
 ### Added

data/lib/uniword/configuration.rb

@@ -3,7 +3,7 @@
 module Uniword
   # Global runtime configuration for Uniword.
   #
-  # Holds save-path policy as plain, explicitly typed boolean attributes.
+  # Holds save-path policy as plain, explicitly typed attributes.
   # This object is runtime policy only: it has no file-loading behavior
   # (see ConfigurationLoader for external YAML config files) and no
   # serialization behavior.
@@ -22,6 +22,15 @@ module Uniword
     autoload :ConfigurationLoader,
              "#{__dir__}/configuration/configuration_loader"
 
+    # Accepted values for `on_noncompliant_content`.
+    #
+    # `:strip` — Word-identical default: non-compliant parts are
+    #   dropped at load and recorded on `Package#stripped_parts`.
+    # `:raise` — strict: parts are preserved; the save-time
+    #   `PackageIntegrityChecker` raises `Uniword::ValidationError`
+    #   with structured OPC-005 issues.
+    ON_NONCOMPLIANT_MODES = %i[strip raise].freeze
+
     # Whether documents are validated when saved.
     #
     # @return [Boolean]
@@ -37,10 +46,16 @@ module Uniword
     # @return [Boolean]
     attr_reader :log_save_fixes
 
+    # Load-time policy for non-compliant parts (no content type
+    # declaration, OS artifact, ...).
+    #
+    # @return [Symbol] `:strip` (default) or `:raise`
+    attr_reader :on_noncompliant_content
+
     # Create a configuration with default policy values.
     #
     # Defaults: validate_on_save: true, xsd_validation: false,
-    # log_save_fixes: true.
+    # log_save_fixes: true, on_noncompliant_content: :strip.
     def initialize
       reset!
     end
@@ -52,6 +67,7 @@ module Uniword
       @validate_on_save = true
       @xsd_validation = false
       @log_save_fixes = true
+      @on_noncompliant_content = :strip
       self
     end
 
@@ -82,6 +98,17 @@ module Uniword
       @log_save_fixes = typed_boolean(value, :log_save_fixes)
     end
 
+    # Set the non-compliant-content policy. Accepts symbols or
+    # strings; stored as a symbol.
+    #
+    # @param value [Symbol, String] `:strip` or `:raise`
+    # @return [Symbol] the value set
+    # @raise [ArgumentError] if value is not one of
+    #   `ON_NONCOMPLIANT_MODES`
+    def on_noncompliant_content=(value)
+      @on_noncompliant_content = typed_mode(value, :on_noncompliant_content)
+    end
+
     private
 
     # Validate that a value is strictly boolean.
@@ -96,5 +123,31 @@ module Uniword
       raise ArgumentError,
             "#{name} must be true or false, got #{value.inspect}"
     end
+
+    # Validate that a value is one of the accepted non-compliant modes.
+    #
+    # @param value [Object] value to check (Symbol or String)
+    # @param name [Symbol] attribute name used in the error message
+    # @return [Symbol] the value as a symbol
+    # @raise [ArgumentError] if value is not in ON_NONCOMPLIANT_MODES
+    def typed_mode(value, name)
+      sym = symbol_value(value)
+      return sym if ON_NONCOMPLIANT_MODES.include?(sym)
+
+      raise ArgumentError,
+            "#{name} must be one of #{ON_NONCOMPLIANT_MODES.inspect}, " \
+            "got #{value.inspect}"
+    end
+
+    # Coerce a value to a Symbol when it is a Symbol or String.
+    #
+    # @param value [Object]
+    # @return [Symbol, nil] nil when value is neither Symbol nor String
+    def symbol_value(value)
+      return value if value.is_a?(Symbol)
+      return value.to_sym if value.is_a?(String)
+
+      nil
+    end
   end
 end

data/lib/uniword/content_types/types.rb

@@ -18,6 +18,33 @@ module Uniword
         map_element "Default", to: :defaults, render_nil: false
         map_element "Override", to: :overrides, render_nil: false
       end
+
+      # Resolve the content type declared for a package-relative path.
+      #
+      # Override entries win; the Default extension match is the
+      # fallback. Returns nil when neither matches (the part is
+      # non-compliant per OPC).
+      #
+      # @param path [String] package-relative path (e.g.
+      #   "word/document.xml")
+      # @return [String, nil] content type, or nil when undeclared
+      def content_type_for(path)
+        override_content_type(path) || default_content_type(path)
+      end
+
+      private
+
+      def override_content_type(path)
+        part_name = "/#{path}"
+        overrides.find { |o| o.part_name == part_name }&.content_type
+      end
+
+      def default_content_type(path)
+        ext = File.extname(path)[1..]
+        return nil unless ext
+
+        defaults.find { |d| d.extension == ext }&.content_type
+      end
     end
   end
 end

data/lib/uniword/docx/junk_classifier.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # Classify a package-relative path as junk or legitimate.
+    #
+    # Used by `Docx::PartLoader::RawPartLoader` to decide which
+    # unclaimed ZIP entries to carry as `RawPart` and which to strip.
+    # The classifier is the single source of truth for the junk
+    # decision — adding new criteria means changing this class (or its
+    # pattern constants), not the loader.
+    #
+    # Classification is two-armed:
+    #
+    # 1. *OS/tooling artifact* — path matches a known pattern
+    #    (`__MACOSX/`, `.DS_Store`, `Thumbs.db`, `._*`, `~$*`). These
+    #    are never legitimate document content; matched unconditionally
+    #    even when a Default content type happens to apply.
+    #
+    # 2. *Undeclared part* — no Override and no Default extension match
+    #    in the loaded `ContentTypes::Types`, AND no modelled
+    #    relationship targets the path. This is the OPC rule: every
+    #    part must have a content type declaration.
+    #
+    # Both arms return a human-readable reason string; the loader
+    # records it on `Package#stripped_parts` for caller introspection.
+    #
+    # @example
+    #   classifier = JunkClassifier.new(
+    #     content_types: package.content_types,
+    #     relationships_by_path: rel_targets,
+    #   )
+    #   classifier.reason("[trash]/0000.dat")
+    #   # => "No content type declaration and no referencing relationship"
+    #   classifier.reason("word/document.xml") # => nil
+    class JunkClassifier
+      # Path patterns for OS / tooling artifacts that are never
+      # legitimate document content. Append to extend; the classifier
+      # iterates them in order.
+      OS_ARTIFACT_PATTERNS = [
+        /\A__MACOSX\//,         # macOS zip metadata directory
+        /\A\.DS_Store\z/,       # macOS Finder
+        /Thumbs\.db\z/,         # Windows Explorer
+        /\A\._/,                # macOS AppleDouble resource fork
+        /\A~\$/,                # Office lock files
+      ].freeze
+
+      OS_ARTIFACT_REASON = "OS or tooling artifact"
+
+      UNDECLARED_REASON =
+        "No content type declaration and no referencing relationship"
+
+      # @param content_types [ContentTypes::Types, nil] the loaded
+      #   content types model (nil when absent — every path is then
+      #   undeclared unless a relationship targets it)
+      # @param relationships_by_path [Hash{String => true}, nil] set of
+      #   paths targeted by some modelled relationship. Encoded as a
+      #   hash for O(1) lookup; nil means "no relationships recorded"
+      def initialize(content_types:, relationships_by_path: nil)
+        @content_types = content_types
+        @relationships_by_path = relationships_by_path || {}
+      end
+
+      # @param path [String] package-relative path
+      # @return [String, nil] reason string when the path is junk;
+      #   nil when it is legitimate
+      def reason(path)
+        os_artifact_reason(path) || undeclared_reason(path)
+      end
+
+      # @param path [String] package-relative path
+      # @return [Boolean] true when the path is junk
+      def junk?(path)
+        !reason(path).nil?
+      end
+
+      private
+
+      def os_artifact_reason(path)
+        OS_ARTIFACT_REASON if OS_ARTIFACT_PATTERNS.any? do |pattern|
+          pattern.match?(path)
+        end
+      end
+
+      def undeclared_reason(path)
+        return nil if content_type_declared?(path)
+        return nil if referenced_by_relationship?(path)
+
+        UNDECLARED_REASON
+      end
+
+      def content_type_declared?(path)
+        @content_types&.content_type_for(path)
+      end
+
+      def referenced_by_relationship?(path)
+        @relationships_by_path.key?(path)
+      end
+    end
+  end
+end

data/lib/uniword/docx/package.rb

@@ -146,6 +146,29 @@ module Uniword
         @applied_fixes ||= []
       end
 
+      # Parts stripped at load because they were non-compliant (no
+      # content type declaration, OS artifact, ...). Populated by
+      # `Docx::PartLoader::RawPartLoader` when
+      # `Uniword.configuration.on_noncompliant_content` is `:strip`
+      # (the default). Empty in `:raise` mode and for packages
+      # constructed by hand.
+      #
+      # @return [Array<StrippedPart>] path + reason for every stripped
+      #   part, in load order
+      def stripped_parts
+        @stripped_parts ||= []
+      end
+
+      # Record a stripped part. Append-only; used by the loader.
+      #
+      # @param path [String] package-relative path
+      # @param reason [String] why the part was stripped (from
+      #   `JunkClassifier#reason`)
+      # @return [void]
+      def add_stripped_part(path:, reason:)
+        stripped_parts << StrippedPart.new(path: path, reason: reason)
+      end
+
       # Load DOCX package from file
       #
       # @param path [String] Path to .docx file

data/lib/uniword/docx/package_serialization.rb

@@ -400,6 +400,11 @@ document_rels)
       # reconciliation untouched (non-standard entries are preserved);
       # a part whose content type came from a Default entry needs an
       # Override once the reconciler rebuilds the standard Defaults.
+      #
+      # Raw parts always carry a non-nil content type: the loader
+      # strips undeclared parts at load (default `:strip` policy), and
+      # API-created raw parts without a content type are a programmer
+      # error that the save-time gate catches as OPC-005.
       def inject_raw_part_content_types(content_types)
         return if raw_parts.empty?
 
@@ -415,7 +420,8 @@ document_rels)
           next if content_types.overrides.any? { |o| o.part_name == part_name }
 
           content_types.overrides << Uniword::ContentTypes::Override.new(
-            part_name: part_name, content_type: part.content_type,
+            part_name: part_name,
+            content_type: part.content_type,
           )
         end
       end

data/lib/uniword/docx/part_loader/raw_part_loader.rb

@@ -17,6 +17,13 @@ module Uniword
       # sidecar) at a non-standard location, or when it is a customXml
       # item rels sidecar consumed by CustomXmlLoader.
       #
+      # Non-compliant parts (no content type declaration, OS artifact,
+      # ...) are stripped at load when
+      # `Uniword.configuration.on_noncompliant_content` is `:strip`
+      # (the default, matching Word's behavior). In `:raise` mode the
+      # parts are preserved and the save-time integrity gate raises
+      # with structured OPC-005 issues.
+      #
       # Bytes are re-read from the original ZIP when available (the
       # extracted hash may carry corrupted UTF-8 binary); content
       # types come from the loaded [Content_Types].xml model.
@@ -32,21 +39,84 @@ module Uniword
         #   by definition matching)
         # @return [void]
         def load(context, _definition)
-          paths = unclaimed_paths(context)
-          return if paths.empty?
+          preservable, stripped = partition_unclaimed(context)
+
+          record_stripped(context, stripped)
+          return if preservable.empty?
 
-          bytes = raw_bytes(context, paths)
-          paths.each do |path|
+          bytes = raw_bytes(context, preservable)
+          rels_by_target = relationships_by_target(context.package)
+
+          preservable.each do |path|
             next unless bytes[path]
 
             context.package.raw_parts[path] = build_part(
-              context.package, path, bytes[path]
+              context.package, path, bytes[path], rels_by_target
             )
           end
         end
 
         private
 
+        # Split unclaimed paths into preservable and stripped based on
+        # the configured policy. In `:raise` mode everything is
+        # preserved (existing behavior); the save-time gate handles
+        # non-compliance.
+        #
+        # @return [Array(Array<String>, Array<String>)] preservable
+        #   paths and stripped paths (each in zip_content order)
+        def partition_unclaimed(context)
+          unclaimed = unclaimed_paths(context)
+          return [unclaimed, []] if raise_mode?
+
+          classifier = build_classifier(context.package)
+          unclaimed.partition { |path| classifier.reason(path).nil? }
+        end
+
+        # @return [Boolean] true when the configured policy is :raise
+        def raise_mode?
+          Uniword.configuration.on_noncompliant_content == :raise
+        end
+
+        # Record stripped parts on the package and log each one when
+        # save-fix logging is enabled.
+        #
+        # @return [void]
+        def record_stripped(context, stripped)
+          return if stripped.empty?
+
+          classifier = build_classifier(context.package)
+          stripped.each do |path|
+            reason = classifier.reason(path)
+            context.package.add_stripped_part(path: path, reason: reason)
+            log_strip(path, reason)
+          end
+        end
+
+        # @return [JunkClassifier] classifier wired to the package's
+        #   content types and relationship targets
+        def build_classifier(package)
+          JunkClassifier.new(
+            content_types: package.content_types,
+            relationships_by_path: relationships_by_target(package),
+          )
+        end
+
+        # @return [Hash{String => Array<Ooxml::Relationships::Relationship>}]
+        #   target path => relationships referencing it. Multiple rels
+        #   may target the same path; the first is used for metadata.
+        #   The classifier uses `key?` only.
+        def relationships_by_target(package)
+          rels_collections(package).each_with_object({}) do |(rels, base), memo|
+            rels&.relationships&.each do |rel|
+              target = rel.target.to_s
+              next if target.empty?
+
+              (memo[resolve_target(base, target)] ||= []) << rel
+            end
+          end
+        end
+
         # @return [Array<String>] ZIP entries claimed by no registry
         #   loader, in zip_content order
         def unclaimed_paths(context)
@@ -71,8 +141,8 @@ module Uniword
         end
 
         # @return [RawPart]
-        def build_part(package, path, content)
-          rel = referencing_relationship(package, path)
+        def build_part(package, path, content, rels_by_target)
+          rel = first_referencing_relationship(rels_by_target, path)
           RawPart.new(
             path: path,
             content: content,
@@ -105,44 +175,23 @@ module Uniword
         end
 
         # Content type the source [Content_Types].xml declared for the
-        # part: its Override first, else the Default for its extension.
+        # part. Delegates to `ContentTypes::Types#content_type_for`
+        # (single source of truth for the lookup).
         #
         # @return [String, nil] nil when the source declared neither
         def content_type_for(package, path)
           content_types = package.content_types
           return nil unless content_types
 
-          override_type(content_types, path) ||
-            default_type(content_types, path)
-        end
-
-        def override_type(content_types, path)
-          part_name = "/#{path}"
-          content_types.overrides.find do |o|
-            o.part_name == part_name
-          end&.content_type
-        end
-
-        def default_type(content_types, path)
-          ext = File.extname(path)[1..]
-          return nil unless ext
-
-          content_types.defaults.find do |d|
-            d.extension == ext
-          end&.content_type
+          content_types.content_type_for(path)
         end
 
-        # The first relationship in a modelled rels part whose
-        # resolved target is this part, or nil. Recorded as metadata
-        # only; the rel itself stays in its rels collection.
-        def referencing_relationship(package, path)
-          rels_collections(package).each do |rels, base_dir|
-            rel = rels&.relationships&.find do |r|
-              resolve_target(base_dir, r.target.to_s) == path
-            end
-            return rel if rel
-          end
-          nil
+        # The first relationship referencing the given path, or nil.
+        # Recorded as metadata only; the rel itself stays in its rels
+        # collection.
+        def first_referencing_relationship(rels_by_target, path)
+          rels = rels_by_target[path]
+          rels.is_a?(Array) ? rels.first : nil
         end
 
         # [rels collection, base directory] pairs mirroring the rels
@@ -177,6 +226,15 @@ module Uniword
           end
           segments.join("/")
         end
+
+        # @return [void]
+        def log_strip(path, reason)
+          return unless Uniword.configuration.log_save_fixes
+
+          Uniword.logger&.info do
+            "Stripped non-compliant part #{path} (#{reason})"
+          end
+        end
       end
     end
   end

data/lib/uniword/docx/stripped_part.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Docx
+    # Reporting record for a part stripped at load time.
+    #
+    # Created by `Docx::PartLoader` (in `:strip` policy mode) for
+    # every ZIP entry the `JunkClassifier` flagged. Stored on
+    # `Package#stripped_parts` for caller introspection.
+    #
+    # Lightweight by design: no lutaml-model, no XML serialization.
+    # These are load-time metadata, never written to a package.
+    #
+    # @example
+    #   part = StrippedPart.new(
+    #     path: "[trash]/0000.dat",
+    #     reason: "No content type declaration and no referencing " \
+    #             "relationship",
+    #   )
+    #   part.path   # => "[trash]/0000.dat"
+    #   part.reason # => "No content type declaration..."
+    class StrippedPart
+      attr_reader :path, :reason
+
+      # @param path [String] package-relative path of the stripped part
+      # @param reason [String] why the part was stripped (human-readable,
+      #   produced by `JunkClassifier#reason`)
+      def initialize(path:, reason:)
+        @path = path
+        @reason = reason
+      end
+
+      # Value-object equality by path + reason.
+      #
+      # @param other [Object]
+      # @return [Boolean]
+      def eql?(other)
+        other.is_a?(StrippedPart) && path == other.path &&
+          reason == other.reason
+      end
+
+      # Combined with `eql?` for Hash/Set membership.
+      #
+      # @return [Integer]
+      def hash
+        [path, reason].hash
+      end
+
+      # @param other [Object]
+      # @return [Boolean]
+      def ==(other)
+        eql?(other)
+      end
+    end
+  end
+end

data/lib/uniword/docx.rb

@@ -10,6 +10,8 @@ module Uniword
     autoload :IdAllocator, "#{__dir__}/docx/id_allocator"
     autoload :Part, "#{__dir__}/docx/part"
     autoload :RawPart, "#{__dir__}/docx/raw_part"
+    autoload :StrippedPart, "#{__dir__}/docx/stripped_part"
+    autoload :JunkClassifier, "#{__dir__}/docx/junk_classifier"
     autoload :ChartPart, "#{__dir__}/docx/chart_part"
     autoload :ImagePart, "#{__dir__}/docx/image_part"
     autoload :HeaderFooterPart, "#{__dir__}/docx/header_footer_part"

data/lib/uniword/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Uniword
-  VERSION = "1.4.1"
+  VERSION = "1.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uniword
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -823,6 +823,7 @@ files:
 - lib/uniword/docx/header_footer_view.rb
 - lib/uniword/docx/id_allocator.rb
 - lib/uniword/docx/image_part.rb
+- lib/uniword/docx/junk_classifier.rb
 - lib/uniword/docx/package.rb
 - lib/uniword/docx/package_defaults.rb
 - lib/uniword/docx/package_integrity_checker.rb
@@ -852,6 +853,7 @@ files:
 - lib/uniword/docx/reconciler/referential_integrity.rb
 - lib/uniword/docx/reconciler/tables.rb
 - lib/uniword/docx/reconciler/theme.rb
+- lib/uniword/docx/stripped_part.rb
 - lib/uniword/drawingml.rb
 - lib/uniword/drawingml/adjust_value_list.rb
 - lib/uniword/drawingml/alpha.rb