canon 0.3.112 → 0.3.113

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afbb918c5dd097f911cfb587efa51b493ceed18976086f141f54373a8ab2c277
-  data.tar.gz: d6ef44bf2617820a71df1ec06b69e50a8436ee4879714f3fe3c9bf070fad8782
+  metadata.gz: c91f395c09165032ecc68e5a79f01c0620a66571411add6b4e083d68b9367d10
+  data.tar.gz: 1bbabc0e6112d88e3743fb20f0cb22f765b1a6d2fa8fd655f31b1bb2b368ce71
 SHA512:
-  metadata.gz: 1f5a7911c15b91176afd697b75e01836f7aec79363df4f79bc504d79d5ae307ec0432151c6cde2ada42071ad95c97bcde03b6e265d23b6ff512e8cf663c5a95a
-  data.tar.gz: 4b35e4166db83dfc545a55c3f89093e09dc1f7d7e1d5b591f1306fac6b49bb7ce0346810fa4484fde9bcbd264dd34f0b5dec0d4d5a66869a2061d54e90afaac1
+  metadata.gz: a94fd8fc2dc5493976494b2a0a3ab9031537d93557005c1a7c51405d4b3a64ab5a07806ac43831a41bddc194db61b231576481e151d994001287ef215c9165d8
+  data.tar.gz: f83ba6f4dc985daa93f062f4bffecd2adaf5a47c77473106263f810112e54e65a6da39163d47c06eb057832abebb7a53f6c0e31ec98ed9b445d1de31574e3ddc

data/docs/_references/comparison-theory.adoc

@@ -0,0 +1,289 @@
+= Canon comparison theory: dimensions, profiles, and the two algorithms
+:toc:
+
+This document is the specification of canon's comparison semantics.
+It is REVIEWED AGAINST THE IMPLEMENTATION by
+`spec/canon/docs/comparison_theory_spec.rb`: every dimension,
+behavior, and profile row cited here must exist in the dimension
+registry and the profile resolvers, and everything the registry
+defines must appear here (docs match shipped behavior — the W6.3
+standing rule).
+
+== 1. The four-layer pipeline
+
+Comparison flows through four independent layers. Each layer's
+output is the next layer's input; no layer sees another layer's
+options.
+
+[cols="1,3,2"]
+|===
+|Layer |Decides |Resolved from
+
+|1. Preprocessing
+|What byte form enters the parse (`:none`, `:c14n`, `:normalize`,
+`:format`, `:rendered`)
+|The profile's `preprocessing` key
+
+|2. Algorithm
+|The comparison engine: `:dom` (position-based recursive descent) or
+`:semantic` (signature matching producing insert/update/delete/move)
+|`diff_algorithm:` (default `:dom`); the two are distinct by design
+and are never merged
+
+|3. Matching
+|How nodes are deemed equal: one behavior per dimension
+|The profile (or explicit per-dimension options) resolved through
+the format's resolver
+
+|4. Presentation
+|How results are spelled (`by_line`, `by_object`, normative-only
+filtering)
+|`show_diffs:` and the formatter choice
+|===
+
+== 2. Dimensions
+
+A *dimension* is one axis along which two nodes may differ. The
+dimension registry (`Canon::Comparison::Dimensions::Registry`)
+defines, per format, each dimension's name and its *valid
+behaviors* — closed sets; an option outside the set raises at
+resolution. HTML aliases (`html`, `html4`, `html5`) resolve to the
+XML dimension set.
+
+=== 2.1 XML and HTML (the `:xml` set)
+
+[cols="1,2,3"]
+|===
+|Dimension |Behaviors |Semantics
+
+|`text_content`
+|`strict`, `normalize`, `ignore`
+|`strict`: character-exact text comparison. `normalize`:
+whitespace runs collapse to a single space and leading/trailing
+whitespace strips before comparison. `ignore`: text content never
+differs.
+
+|`structural_whitespace`
+|`strict`, `normalize`, `ignore`
+|Whitespace-only text nodes between elements. `strict`: they are
+content (normative: a `strict`-only dimension — a non-strict
+behavior can never make documents inequivalent on its own).
+`normalize`: whitespace-only nodes are equivalent regardless of
+shape. `ignore`: whitespace-only nodes are dropped before the walk.
+
+|`attribute_presence`
+|`strict`, `ignore`
+|Whether an attribute exists. `ignore` drops all attributes before
+comparison.
+
+|`attribute_order`
+|`strict`, `ignore`
+|`strict`: attribute order is significant. `ignore`: attributes
+compare as a set.
+
+|`attribute_values`
+|`strict`, `strip`, `compact`, `normalize`, `ignore`
+|`strict`: character-exact values. `strip`: leading/trailing
+whitespace strips. `compact`: internal whitespace runs collapse
+(verify: the value is compared after whitespace compaction).
+`normalize`: both strip and collapse. `ignore`: values compare
+equal regardless.
+
+|`element_position`
+|`strict`, `ignore`
+|`strict`: child order is significant. `ignore`: children match by
+identity (the ElementMatcher's id-attribute matching), not position.
+
+|`comments`
+|`strict`, `ignore`
+|Comment nodes: content-compared or dropped.
+
+|`namespace_prefix`
+|`significant`, `ignore`
+|`significant`: the written prefix is part of the node's identity.
+`ignore`: only the namespace URI matters; the prefix is spelling.
+|===
+
+=== 2.2 JSON (the `:json` set)
+
+[cols="1,2,3"]
+|===
+|Dimension |Behaviors |Semantics
+
+|`text_content`
+|`strict`, `normalize`, `ignore`
+|String values, `strict` character-exact.
+
+|`structural_whitespace`
+|`strict`, `normalize`, `ignore`
+|Whitespace between tokens outside strings. `strict`-only
+normative.
+
+|`key_order`
+|`strict`, `ignore`
+|`ignore`: objects compare as unordered maps (the canonical lane
+sorts keys).
+|===
+
+=== 2.3 YAML (the `:yaml` set)
+
+The `:json` set plus:
+
+[cols="1,2,3"]
+|===
+|Dimension |Behaviors |Semantics
+
+|`comments`
+|`strict`, `ignore`
+|YAML comments: compared or dropped before parse.
+|===
+
+== 3. Profiles and the profile algebra
+
+A *profile* is a named total assignment: one behavior per dimension
+of the format, plus a preprocessing layer. Profiles resolve through
+the format's resolver; explicit per-dimension options override a
+profile's entry for that dimension alone. XML/HTML ship FOUR
+profiles; JSON and YAML ship THREE (`:rendered` does not exist for
+them — the resolvers reject it). The resolved assignments below are
+asserted by the review spec:
+
+[cols="1,1,1"]
+|===
+|Profile |Intent |Resolved assignment
+
+|`:strict`
+|Default. Everything significant.
+|`text_content=strict`, `structural_whitespace=strict`,
+`attribute_presence=strict`, `attribute_order=strict`,
+`attribute_values=strict`, `element_position=strict`,
+`comments=strict`, `namespace_prefix=significant`,
+`whitespace_type=strict`, `preprocessing=none`.
+
+|`:spec_friendly`
+|Normative-document comparison (the spec-familiar shape).
+|`text_content=normalize`, `structural_whitespace=ignore`,
+`attribute_presence=strict`, `attribute_values=normalize`,
+`attribute_order=ignore`, `element_position=ignore`,
+`comments=ignore`, `namespace_prefix=ignore`,
+`whitespace_type=strict`, `preprocessing=rendered`.
+
+|`:rendered` (XML/HTML only)
+|The same document as rendered sources.
+|`text_content=normalize`, `structural_whitespace=normalize`,
+`attribute_presence=strict`, `attribute_order=ignore`,
+`comments=ignore`, `attribute_values=strict`,
+`element_position=strict`, `namespace_prefix=significant`,
+`whitespace_type=strict`, `preprocessing=none`.
+
+|`:content_only`
+|Ignore all spelling; compare information content.
+|`text_content=normalize`, `structural_whitespace=ignore`,
+`attribute_presence=strict`, `attribute_order=ignore`,
+`attribute_values=normalize`, `element_position=ignore`,
+`comments=ignore`, `namespace_prefix=ignore`,
+`whitespace_type=strict`, `preprocessing=c14n`.
+|===
+
+=== 3.1 JSON and YAML profile assignments
+
+JSON ships `:strict`, `:spec_friendly`, and `:content_only` (no
+`:rendered`); YAML the same plus its `comments` dimension.
+
+[cols="1,1,1"]
+|===
+|Profile |JSON |YAML
+
+|`:strict`
+|`key_order=strict`, `text_content=strict`,
+`structural_whitespace=strict`, `preprocessing=none`
+|`key_order=strict`, `text_content=strict`,
+`structural_whitespace=strict`, `comments=strict`,
+`preprocessing=none`
+
+|`:spec_friendly`
+|`key_order=ignore`, `text_content=strict`,
+`structural_whitespace=ignore`, `preprocessing=normalize`
+|`key_order=ignore`, `text_content=strict`,
+`structural_whitespace=ignore`, `comments=ignore`,
+`preprocessing=normalize`
+
+|`:content_only`
+|`key_order=ignore`, `text_content=normalize`,
+`structural_whitespace=ignore`, `preprocessing=normalize`
+|`key_order=ignore`, `text_content=normalize`,
+`structural_whitespace=ignore`, `comments=ignore`,
+`preprocessing=normalize`
+|===
+
+*Registry note (the W6.2 audit finding)*: the resolvers resolve
+one key beyond the registry's dimension sets — `whitespace_type`
+(`strict` in every shipped profile) — governing whether whitespace
+TYPE differences (space vs tab) are significant. It awaits registry
+promotion; until then it is documented here as a resolver-level
+option.
+
+Profile algebra properties:
+
+* *Totality*: a resolved profile assigns every format dimension
+exactly one behavior (the resolver raises on a gap).
+* *Monotone relaxation*: `:strict` is the identity of the algebra —
+every other profile differs from `:strict` only by relaxing
+dimensions toward `ignore`/`normalize`, never by strengthening.
+* *Non-normativity of relaxed dimensions*: with the exception of
+`text_content`, a dimension at `ignore` contributes no
+equivalence-affecting differences (the normative/informative split
+below).
+
+== 4. Normative, informative, and formatting-only differences
+
+A difference is classified when emitted:
+
+* *Normative* — affects equivalence: the documents are not
+equivalent. Produced by a dimension at a strict/significant
+behavior.
+* *Informative* — recorded but not equivalence-affecting: produced
+by a dimension at a relaxed behavior where the difference is still
+observable.
+* *Formatting-only* — the canonical forms match; the difference is
+pure spelling.
+
+`show_diffs: :normative` filters the presentation to normative
+findings. The classification is a property of the dimension's
+resolved behavior, not of the documents.
+
+== 5. The two algorithms
+
+=== 5.1 DOM (`diff_algorithm: :dom`, default)
+
+Position-based recursive descent. For each element pair: compare
+names, dimensions resolve per-dimension (attributes as sets or
+sequences per `attribute_order`, children positionally per
+`element_position` with the ElementMatcher's identity matching when
+relaxed). Complexity is linear in the sum of tree sizes. The
+intermediate representation is comparison-result codes
+(`EQUIVALENT`, `MISSING_NODE`, `UNEQUAL_TEXT_CONTENTS`, ...) which
+convert to DiffNodes.
+
+=== 5.2 Semantic (`diff_algorithm: :semantic`)
+
+Signature-based tree matching in three phases: (1) hash matching —
+identical subtrees match exactly; (2) similarity matching —
+remaining nodes pair by content similarity above
+`similarity_threshold`; (3) structural propagation — parent/child
+correspondences derive from matched ancestors. The intermediate
+representation is an operation stream (INSERT, DELETE, UPDATE,
+MOVE) converted to DiffNodes. The algorithms share preprocessing,
+configuration, match options, and output formatting; the comparison
+cores never share code (distinct by design — see CLAUDE.md, "Two
+Comparison Algorithms — Distinct by Design").
+
+== 6. Registry citation
+
+The review spec (`spec/canon/docs/comparison_theory_spec.rb`)
+asserts, at every run: for each format, every registry dimension
+name and every valid behavior token appears in this document; every
+profile row's resolved assignment equals the resolver's output for
+that profile. A dimension added to the registry without a §2 entry,
+a behavior added without its semantics row, or a profile change
+without a §3 row update, fails the battery.

data/lib/canon/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.112
+  version: 0.3.113
 platform: ruby
 authors:
 - Ribose Inc.
@@ -173,6 +173,7 @@ files:
 - docs/Gemfile
 - docs/INDEX.adoc
 - docs/_config.yml
+- docs/_references/comparison-theory.adoc
 - docs/advanced/diff-classification.adoc
 - docs/advanced/diff-pipeline.adoc
 - docs/advanced/extending-canon.adoc