canon 0.3.107 → 0.3.109

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71d7579e878aed3d0a9a47f8fefb19e6f4ab9f89473c00a60e8bc81b26b5d002
-  data.tar.gz: e50f13237f3e56176571756f9358c94d300b04c07ee78fe3b4b0db75a8eb8894
+  metadata.gz: ebfe19fb1f87ac9ec65e4fc2ba727bbe97b3b8d0f9733184588217e82753e9f9
+  data.tar.gz: 301b3d96f9ffebce87022cdfef4d538ab512ea6f832bdfd3f2c39c164a996069
 SHA512:
-  metadata.gz: 8c01df75477add69c04573c3b15c2a763f0159729f955be2433000b28a1e58fa8dd7954b313feb37abb109dc68ff91ac6ddf38fbf0ecb145b27b421dbb10bcee
-  data.tar.gz: 37e3111d28f06a0d34942e79811796a14ecf69792b04cbe075dd7a69caf5bd225537e3b6ee3a6cdf166ea296a5c88545530748bd636d0cf9fec0829ff33d5541
+  metadata.gz: cb97c29a9ab623568ac2ea936710a42694b7d4863e0075ee90dce47f3ff01faba53a695e66abde1ce680ef3d53da4e31a7c9b8ed9a6f883dac08d48dc3757c66
+  data.tar.gz: e4b4a46d00abe224d9bf541cc248220aa984caec768f3d2173be3b00c8471234141ae872dbc6273445b3be6434c8a027ad98e8ffba1045b8a712ee54bf2d8f35

data/lib/canon/formatters/html_formatter_base.rb

@@ -63,6 +63,12 @@ module Canon
       # regex per format call cost more than the gsub it drives.
       BLOCK_SPACING_PATTERN =
         Regexp.new("(</(?:#{BLOCK_ELEMENTS.join('|')})>)(?:\n*)(<(?:#{BLOCK_ELEMENTS.join('|')})[\s>])").freeze
+      # Engine-inserted newlines after a block close, before ANY next
+      # tag (the serializer's indent model breaks lines where canon's
+      # normalize step kept no text node) — folded to the canonical
+      # single space so serialization is idempotent.
+      AFTER_BLOCK_NEWLINE_PATTERN =
+        Regexp.new("(</(?:#{BLOCK_ELEMENTS.join('|')})>)(\n+)(<(?!/))").freeze
       # Format HTML using canonical form
       # @param html [String] HTML document to canonicalize
       # @return [String] Canonical form of HTML
@@ -108,21 +114,10 @@ module Canon
       end
 
       # Sort element attributes alphabetically throughout document
+      # (the shared canonical attribute order — TODO.sota/03)
       # @param doc [Moxml::Document] Parsed document
       def self.sort_attributes(doc)
-        walk_elements(doc.root) do |element|
-          attrs = element.attributes
-          next if attrs.empty?
-
-          names = attrs.map(&:name)
-          # Already-sorted is the common case — removing and re-adding
-          # every attribute is expensive, so check first.
-          next if names.each_cons(2).all? { |a, b| (a <=> b) <= 0 }
-
-          sorted_attrs = attrs.sort_by(&:name)
-          names.each { |name| element.remove_attribute(name) }
-          sorted_attrs.each { |attr| element[attr.name] = attr.value }
-        end
+        Canon::Xml::AttributeSorter.sort!(doc)
       end
 
       # Depth-first element walk (pre-order).
@@ -211,9 +206,17 @@ module Canon
       # @param html [String] Serialized HTML string
       # @return [String] HTML with proper spacing between block elements
       def self.ensure_block_element_spacing(html)
-        # Add space between closing and opening block element tags
+        # Space between closing and opening block element tags
         # (pattern compiled once — see BLOCK_SPACING_PATTERN)
-        html.gsub(BLOCK_SPACING_PATTERN, '\1 \2')
+        html = html.gsub(BLOCK_SPACING_PATTERN, '\1 \2')
+        # The engine's serializer inserts its own newlines after a
+        # block close when the tree has no whitespace text node there
+        # (normalize_whitespace keeps a single space only where one
+        # existed). Collapse those self-inserted newlines to the same
+        # canonical space — without this, format is not idempotent:
+        # pass 1 emits "</p>\n<br>", pass 2 answers "</p> <br>"
+        # (the property suite, TODO.sota/03).
+        html.gsub(AFTER_BLOCK_NEWLINE_PATTERN, '\1 \3')
       end
 
       # Check if a node is a block-level element

data/lib/canon/formatters/xml_formatter.rb

@@ -11,13 +11,9 @@ module Canon
         end
       end
 
-      def self.parse(xml)
+      def self.parse(xml, options = {})
         Canon::Validators::XmlValidator.validate!(xml)
-        if XmlBackend.nokogiri?
-          Nokogiri::XML(xml)
-        else
-          XmlParsing.parse(xml)
-        end
+        XmlParsing.parse(xml, options)
       end
     end
   end

data/lib/canon/json/jcs.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Canon
+  module Json
+    # RFC 8785 — the I-JSON Canonicalization Scheme (JCS).
+    #
+    # Produces the canonical JSON form the RFC defines: UTF-8, object
+    # keys sorted by their UTF-16 code units, ECMAScript
+    # `Number::toString` number serialization, RFC 8785 §3.2.2.2
+    # string escaping, and no insignificant whitespace. The result is
+    # byte-stable across platforms and suitable for hashing and
+    # signing.
+    #
+    # Input must be I-JSON (RFC 7493): valid UTF-8 without lone
+    # surrogates, no duplicate object keys, numbers expressible as
+    # IEEE 754 doubles. Violations raise {Canon::Json::JCS::Error}.
+    module JCS
+      class Error < ::Canon::Error; end
+
+      module_function
+
+      # @param json [String, Hash, Array] an I-JSON document or an
+      #   already-parsed Ruby object graph
+      # @return [String] the RFC 8785 canonical form
+      def canonicalize(json)
+        doc = json.is_a?(String) ? ::JSON.parse(json) : json
+        serialize(doc)
+      end
+
+      def serialize(value)
+        out = +""
+        write(value, out)
+        out
+      end
+
+      def write(value, out)
+        case value
+        when Hash
+          write_object(value, out)
+        when Array
+          out << "["
+          value.each_with_index do |item, i|
+            out << "," if i.positive?
+            write(item, out)
+          end
+          out << "]"
+        when String
+          out << escape_string(value)
+        when Integer
+          out << ijson_integer(value)
+        when Float
+          out << es6_number(value)
+        when true then out << "true"
+        when false then out << "false"
+        when nil then out << "null"
+        else
+          raise Error, "JCS input must be JSON data; got #{value.class}"
+        end
+      end
+
+      def write_object(hash, out)
+        out << "{"
+        hash.keys.sort_by { |key| utf16_code_units(key) }
+          .each_with_index do |key, i|
+          out << "," if i.positive?
+          out << escape_string(key) << ":"
+          write(hash[key], out)
+        end
+        out << "}"
+      end
+
+      # RFC 8785 §3.2.2.2 — the JSON.stringify escaping set: short
+      # forms for \b \t \n \f \r, two-hex lowercase \u00xx for the
+      # remaining C0 controls, \" and \\; every other code point is
+      # emitted verbatim as UTF-8 (DEL U+007F is NOT escaped).
+      SHORT_ESCAPES = {
+        0x08 => "\\b", 0x09 => "\\t", 0x0A => "\\n",
+        0x0C => "\\f", 0x0D => "\\r"
+      }.freeze
+
+      def escape_string(string)
+        out = +"\""
+        string.each_codepoint do |cp|
+          out << case cp
+                 when 0x22 then "\\\""
+                 when 0x5C then "\\\\"
+                 when 0x08, 0x09, 0x0A, 0x0C, 0x0D then SHORT_ESCAPES[cp]
+                 when 0x00..0x1F then format("\\u%04x", cp)
+                 else
+                   cp.chr(Encoding::UTF_8)
+                 end
+        end
+        out << "\""
+      rescue ArgumentError
+        raise Error, "JCS input must be valid UTF-8 without lone surrogates"
+      end
+
+      # RFC 8785 §2.1 (I-JSON): numbers must be expressible as IEEE
+      # 754 doubles; anything wider is a contract violation, not a
+      # rounding opportunity.
+      def ijson_integer(value)
+        if value.abs > 9_007_199_254_740_992 # 2**53
+          raise Error,
+                "JCS input must be I-JSON: #{value} exceeds the IEEE 754 " \
+                "double range for exact integers"
+        end
+        value.to_s
+      end
+
+      # ECMA-262 `Number::toString` (the JSON.stringify number shape):
+      # shortest-round-trip digits formatted per the spec's fixed /
+      # exponential cases, with the boundaries 1e-6 (inclusive fixed
+      # on the small side) and 1e21 (exclusive fixed on the large
+      # side). -0.0 serializes as "0"; non-finite values are not
+      # JSON data and raise.
+      def es6_number(value)
+        raise Error, "JCS input must be finite numbers" if
+          value.nan? || value.infinite?
+        return "0" if value.zero?
+
+        sign = value.negative? ? "-" : ""
+        s = value.abs.to_s
+        if (m = s.match(/\A(\d+)(?:\.(\d+))?(?:e([+-]?\d+))?\z/))
+          int_part = m[1]
+          frac = m[2] || ""
+          exp = m[3] ? m[3].to_i : 0
+          digits = (int_part + frac).sub(/\A0+/, "")
+          k = int_part.length + exp - (int_part.length + frac.length - digits.length)
+          digits = digits.sub(/0+\z/, "")
+          digits = "0" if digits.empty?
+          n = digits.length
+          return sign + format_digits(digits, n, k)
+        end
+        # Float#to_s always matches above; the fallthrough is defensive
+        raise Error, "unserializable number: #{s}"
+      end
+
+      # n and k are ECMA-262 7.1.12.1's own notation (digit count and
+      # the decimal-point position); renamed parameters would lose the
+      # spec mapping.
+      # rubocop:disable Naming/MethodParameterName
+      def format_digits(digits, n, k)
+        if k <= 0
+          # 0.s × 10^k: fixed for -6 < k <= 0 ("0." + zeros + digits),
+          # exponential at k <= -6 (values below 1e-6, ECMA boundary)
+          return exp_form(digits, k) if k <= -6
+
+          ["0.", "0" * -k, digits].join
+        elsif k >= n
+          return digits if k == n
+
+          # integer-shaped: pad zeros while k <= 21 ("1" + twenty
+          # zeros for 1e20); exponential above (1e21 -> "1e+21")
+          return exp_form(digits, k) if k > 21
+
+          digits + ("0" * (k - n))
+        else
+          # 0 < k < n: the point sits inside the digit string
+          "#{digits[0, k]}.#{digits[k..]}"
+        end
+      end
+
+      def exp_form(digits, k)
+        mantissa = digits.length == 1 ? digits : "#{digits[0]}.#{digits[1..]}"
+        e = k - 1
+        "#{mantissa}e#{e.negative? ? '-' : '+'}#{e.abs}"
+      end
+      # rubocop:enable Naming/MethodParameterName
+
+      # RFC 8785 §3.2.3: keys sort by their UTF-16 code units (the
+      # ECMAScript array sort). Ruby string <=> compares by codepoint,
+      # which diverges from UTF-16 order above the BMP (astral planes
+      # sort after U+E000..U+FFFF in UTF-16 order).
+      def utf16_code_units(string)
+        string.encode("UTF-16LE").unpack("v*")
+      rescue Encoding::UndefinedConversionError
+        raise Error,
+              "JCS keys must be valid UTF-16 (no lone surrogates): " \
+              "#{string.inspect}"
+      end
+    end
+  end
+end

data/lib/canon/json.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Canon
+  module Json
+    autoload :JCS, "canon/json/jcs"
+  end
+end

data/lib/canon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Canon
-  VERSION = "0.3.107"
+  VERSION = "0.3.109"
 end

data/lib/canon/xml/attribute_sorter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Canon
+  module Xml
+    # Canonical attribute ordering: every element's attributes are
+    # re-attached in lexicographic name order. Both canonical lanes
+    # consume this — the HTML formatter base and the XML pretty
+    # printer — so attribute order is invariant across formats and
+    # across input orderings (the equivalence-respect property,
+    # TODO.sota/03).
+    module AttributeSorter
+      module_function
+
+      def sort!(doc)
+        walk_elements(doc.root) do |element|
+          attrs = element.attributes
+          next if attrs.empty?
+
+          names = attrs.map(&:name)
+          # Already-sorted is the common case — removing and re-adding
+          # every attribute is expensive, so check first.
+          next if names.each_cons(2).all? { |a, b| (a <=> b) <= 0 }
+
+          sorted_attrs = attrs.sort_by(&:name)
+          names.each { |name| element.remove_attribute(name) }
+          sorted_attrs.each { |attr| element[attr.name] = attr.value }
+        end
+        doc
+      end
+
+      def walk_elements(node, &block)
+        return unless node.is_a?(Moxml::Element)
+
+        yield(node)
+        node.children.to_a.each { |child| walk_elements(child, &block) }
+      end
+    end
+  end
+end

data/lib/canon/xml.rb

@@ -15,6 +15,7 @@ module Canon
   # Canon::Xml::Nodes.
   module Xml
     autoload :AttributeHandler, "canon/xml/attribute_handler"
+    autoload :AttributeSorter, "canon/xml/attribute_sorter"
     autoload :C14n, "canon/xml/c14n"
     autoload :DigestGate, "canon/xml/digest_gate"
     autoload :CharacterEncoder, "canon/xml/character_encoder"

data/lib/canon/xml_parsing.rb

@@ -303,11 +303,14 @@ module Canon
 
       # --- Moxml engine ---
 
-      # Readonly: canon only ever reads engine documents (conversion,
+      # Readonly by default: canon reads engine documents (conversion,
       # serialization) — leptris memoizes reads on readonly documents,
       # and mutation is refused loudly rather than silently corrupting.
-      def moxml_parse(xml_string, _options)
-        moxml_context.parse(xml_string, readonly: true)
+      # Mutating lanes (the attribute sorter, TODO.sota/03) opt out
+      # explicitly with readonly: false.
+      def moxml_parse(xml_string, options)
+        readonly = options.fetch(:readonly, true)
+        moxml_context.parse(xml_string, readonly: readonly)
       end
 
       def moxml_node_type(node)

data/lib/canon.rb

@@ -32,6 +32,7 @@ module Canon
   autoload :Cli, "canon/cli"
   autoload :ColorDetector, "canon/color_detector"
   autoload :DiffFormatter, "canon/diff_formatter"
+  autoload :Json, "canon/json"
 
   SUPPORTED_FORMATS = %i[xml yaml json html html4 html5 string].freeze
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.107
+  version: 0.3.109
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -347,6 +347,8 @@ files:
 - lib/canon/html.rb
 - lib/canon/html/data_model.rb
 - lib/canon/html/nokogiri_support.rb
+- lib/canon/json.rb
+- lib/canon/json/jcs.rb
 - lib/canon/json_parsing.rb
 - lib/canon/nokogiri_loader.rb
 - lib/canon/options.rb
@@ -403,6 +405,7 @@ files:
 - lib/canon/version.rb
 - lib/canon/xml.rb
 - lib/canon/xml/attribute_handler.rb
+- lib/canon/xml/attribute_sorter.rb
 - lib/canon/xml/c14n.rb
 - lib/canon/xml/character_encoder.rb
 - lib/canon/xml/data_model.rb