canon 0.3.116 → 0.3.117

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89df5f303938b98100a1d44399c7eb5fbbf793f0f91c445c4f0533a19234d5ec
-  data.tar.gz: 1308c9228b0a6efc15e81ebef134c7495aadd100e10978a23ee09b92ad558555
+  metadata.gz: 223b5ab0201bbebfe8bfee1de2f23229260f574bd6d42fed426256b199f03d6c
+  data.tar.gz: 803eaba7a9fd850a38669c9ea2bbd567503fbc936fd39147a473d2526b3539ce
 SHA512:
-  metadata.gz: 93cfb6bca734697c5cc79173dac20bbe53cb4fb17e72fc72e7aa726af366c187c09ae0c30e5a775d9ea8b9e94f1194b29657f9da3d44c58f6fbc116717e39909
-  data.tar.gz: 37f713fb17fe7961cb622f42c96605cf0bb19227a6831018d0505afdc33ad2e315e54b1a65145219457e30d8b0c6d06d001869611bbe94f55b443c2cbf0e4252
+  metadata.gz: 24ae7e292b598242df4c98bad7d98d98815d7d28ddebd6d1ed79df4451e40017cd3840f2a3556bf4b78681ee7b6653ee91a67623d806d2aec1d8e170093a19d8
+  data.tar.gz: 35a5642e0e6b5b0268935d6888470614058888a3e4cc33d587ea079737a3817b9543aa63fbae986da95240a2c4c72174419eae1fba9336e871859ae6aae6ee3d

data/docs/_references/canonical-digests.adoc

@@ -0,0 +1,50 @@
+= The canonical digests (W5.3)
+
+This document specifies canon's canonical digest API as shipped by
+`Canon::Digest`. Reviewed against the implementation by
+`spec/canon/docs/canonical_digests_spec.rb` (the W6.3 review-gate
+pattern), with the cross-release byte pins carried by
+`spec/canon/digest_stability_spec.rb`.
+
+== 1. The law
+
+The digest of a document is the OpenSSL hash of its CANONICAL
+FORM — the form under which the format's comparison pipeline deems
+documents equivalent. Two documents that compare equivalent produce
+identical digests; two that compare distinct produce distinct
+digests. The digest is an API over the comparison semantics, not a
+new canonicalization.
+
+== 2. Per-format canonical forms
+
+* *XML* rides Canonical XML 1.1
+  (`Canon::Xml::C14n.canonicalize`, reached as
+  `Formatters::XmlFormatter.format(pretty: false)`). The
+  pretty-printed XML form preserves attribute order and is NOT
+  canonical; the digest lane never touches it.
+* *JSON and YAML* ride the key-sorted formatter forms (the JCS
+  profile for JSON's canonical lane; the `[class, to_s]` TOTAL
+  key order for YAML).
+* *HTML* rides the whitespace-law form with sorted attributes
+  (the W1.3 specification).
+
+Equivalence consequences the digest inherits: attribute order is
+insignificant in XML and HTML; mapping key order is insignificant
+in JSON and YAML; element/sequence order is significant everywhere.
+
+== 3. Entry points
+
+`Canon::Digest.digest(content, format, algorithm: "sha256")`
+accepts any OpenSSL digest name; `canonical_form(content, format)`
+exposes the hashed bytes. Per-format shorthands
+(`Canon.digest_xml`, `digest_yaml`, `digest_json`, ...) mirror the
+format lane's shorthands.
+
+== 4. Stability contract
+
+The digests are stable across releases for as long as the
+underlying canonical form is. The stability suite pins the digest
+hex of a representative document per format; a canonical-form
+change moves a digest and MUST fail that suite, forcing a
+conscious pin update (and a release note) rather than silent drift
+for downstream dedup stores.

data/docs/_references/jcs-rfc8785.adoc

@@ -0,0 +1,52 @@
+= The JCS canonical profile (W6.1, RFC 8785)
+
+This document specifies canon's JSON JCS canonical form as shipped
+by `Canon::Json::JCS`. Reviewed against the implementation by
+`spec/canon/docs/jcs_spec_review.rb` (the W6.3 review-gate
+pattern).
+
+== 1. Scope
+
+RFC 8785 — the I-JSON Canonicalization Scheme. 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`.
+
+== 2. The canonical laws
+
+* *Strings* (`escape_string`): RFC 8785 §3.2.2.2 — the
+  JSON.stringify escaping set: short forms for `\b \t \n \f \r`
+  (the SHORT_ESCAPES table), two-hex lowercase `\u00xx` for the
+  remaining C0 controls, `\"` and `\\`; every other code point
+  emits verbatim as UTF-8 (DEL U+007F is NOT escaped).
+
+* *Numbers* (`es6_number`): ECMAScript `Number::toString`
+  serialization — the shortest round-tripping decimal, fixed
+  notation inside [1e-6, 1e21), exponential outside; integers
+  via `ijson_integer` (the I-JSON 2^53 range).
+
+* *Object keys* (`write_object`): sorted by their
+  UTF-16 code units (`utf16_code_units` — the RFC's sort is over
+  UTF-16 code units, not code points, so surrogate pairs and BMP
+  characters interleave per the RFC's examples; e.g. the key
+  U+1D160 (a surrogate pair, code units 0xD834 0xDD60) sorts
+  BEFORE U+20AC (a single BMP code unit 0x20AC), which sorts
+  BEFORE "a" (0x0061)).
+
+* *Containers*: arrays comma-separated in order; objects
+  comma-separated in sorted key order; no whitespace anywhere.
+
+== 3. Entry points
+
+`canonicalize(json)` accepts a JSON string (parsed through
+`JSON.parse`) or an already-parsed Ruby graph; `serialize(value)`
+skips the parse. The canonical form is byte-stable across
+platforms and suitable for hashing and signing.
+
+== 4. Fixed point and parity
+
+JCS output re-parses to the same graph, and the form is a fixed
+point. The phase 02 property suite (JSON/YAML equivalence legs)
+and the diff-display corpus pin the behavior; the JCS spec
+vectors (RFC 8785 §3.2.3 examples) pin the number and sorting
+laws.

data/lib/canon/version.rb

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

data/lib/canon/xml/exclusive_c14n.rb

@@ -55,12 +55,30 @@ module Canon
       # — every node in the subtrees rooted at pfx:name. Returns
       # [prefix, local_name], or nil for anything else.
       def self.c14n_selection_idiom(xpath)
-        # the suite's .xpath files are XML documents wrapping the
-        # expression (with prefix declarations and inline comments)
-        text = xpath.sub(/\A<\?xml[^?]*\?>/, "")
-          .gsub(/<!--[\s\S]*?-->/, "")
-          .gsub(/<[^>]*>/, " ")
-          .squeeze(" ")
+        # The suite's .xpath files are XML documents wrapping the
+        # expression (with prefix declarations and inline comments).
+        # Extraction is index-based string surgery — the CodeQL
+        # polynomial-redos query flags the gsub-chain form.
+        close_tag = xpath.rindex("</XPath>")
+        text = close_tag ? xpath[0...close_tag] : xpath.dup
+        # drop the XML declaration and the <XPath> open tag: each
+        # ends at the first '>' at/after its '<'
+        if (decl = text.index("<"))
+          gt = text.index(">", decl)
+          if (xopen = text.index("<XPath", decl)) && (xopen < gt)
+            gt = text.index(">", xopen)
+          end
+          text = text[(gt + 1)..] if gt
+        end
+        # strip <!-- --> comments by index (no regex backtracking)
+        loop do
+          open_c = text.index("<!--")
+          break unless open_c
+
+          close_c = text.index("-->", open_c + 4)
+          text = close_c ? text[0...open_c] + text[(close_c + 3)..] : text[0...open_c]
+        end
+        text = text.squeeze(" ")
         m = text.match(%r{\(//\.\s*\|\s*//@\*\s*\|\s*//namespace::\*\)\s*\[\s*ancestor-or-self::([A-Za-z_][\w.-]*)(?::([\w.-]+))?\s*\]\s*\z})
         return nil unless m
 

data/lib/tasks/performance_comparator.rb

@@ -30,16 +30,33 @@ class PerformanceComparator
   DIM    = "\e[2m"
   CLEAR  = "\e[0m"
 
+  BEST_OF = Integer(ENV.fetch("CANON_PERF_BEST_OF", "3"))
+
   def run
     clone_base
-    current = run_report(REPO_ROOT, "current")
-    base = run_report(base_clone_dir, "base (#{DEFAULT_BASE})")
+    current = best_of(REPO_ROOT, "current")
+    base = best_of(base_clone_dir, "base (#{DEFAULT_BASE})")
     print_report(current, base)
     exit(1) if regressions?(current, base)
   ensure
     cleanup
   end
 
+  # The html_parsing lanes drift up to ~27% BETWEEN SAME-CONTENT runs
+  # on shared runners (main failed against itself: run 40047205814) —
+  # single-run comparisons measure the runner, not the code. Each side
+  # runs BEST_OF times; per benchmark, the run with the highest upper
+  # bound stands (the capability estimate a fair gate compares).
+  def best_of(working_dir, label)
+    runs = Array.new(BEST_OF) { |i| run_report(working_dir, "#{label} ##{i + 1}") }
+    runs.first.fetch("benchmarks").keys.each_with_object({}) do |bench, merged|
+      best = runs.max_by { |r| r.fetch("benchmarks").fetch(bench).fetch("upper").to_f }
+      merged[bench] = best.fetch("benchmarks").fetch(bench)
+    end.then do |benchmarks|
+      runs.first.merge("benchmarks" => benchmarks)
+    end
+  end
+
   private
 
   def clone_base

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.116
+  version: 0.3.117
 platform: ruby
 authors:
 - Ribose Inc.
@@ -173,8 +173,10 @@ files:
 - docs/Gemfile
 - docs/INDEX.adoc
 - docs/_config.yml
+- docs/_references/canonical-digests.adoc
 - docs/_references/comparison-theory.adoc
 - docs/_references/html-canonical-form.adoc
+- docs/_references/jcs-rfc8785.adoc
 - docs/_references/yaml-canonical-form.adoc
 - docs/advanced/diff-classification.adoc
 - docs/advanced/diff-pipeline.adoc