RubyGems - canon - Versions diffs - 0.1.23 → 0.2.1 - Mend

canon 0.1.23 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (56) hide show

checksums.yaml +4 -4
data/.rubocop_todo.yml +155 -30
data/docs/INDEX.adoc +4 -0
data/docs/advanced/diff-classification.adoc +3 -2
data/docs/advanced/verbose-mode-architecture.adoc +23 -0
data/docs/features/configuration-profiles.adoc +288 -0
data/docs/features/diff-formatting/character-visualization.adoc +153 -454
data/docs/features/diff-formatting/display-filtering.adoc +44 -0
data/docs/features/diff-formatting/display-preprocessing.adoc +656 -0
data/docs/features/diff-formatting/index.adoc +47 -0
data/docs/features/diff-formatting/pretty-diff-mode.adoc +154 -0
data/docs/features/environment-configuration/override-system.adoc +10 -3
data/docs/features/index.adoc +9 -0
data/docs/features/match-options/html-policies.adoc +3 -0
data/docs/features/match-options/index.adoc +32 -42
data/docs/features/match-options/pretty-printed-fixtures.adoc +270 -0
data/docs/guides/choosing-configuration.adoc +22 -0
data/docs/reference/environment-variables.adoc +121 -1
data/docs/reference/options-across-interfaces.adoc +182 -2
data/lib/canon/cli.rb +20 -0
data/lib/canon/commands/diff_command.rb +7 -2
data/lib/canon/commands/format_command.rb +1 -1
data/lib/canon/comparison/html_comparator.rb +29 -19
data/lib/canon/comparison/html_compare_profile.rb +4 -4
data/lib/canon/comparison/markup_comparator.rb +12 -3
data/lib/canon/comparison/match_options/base_resolver.rb +29 -7
data/lib/canon/comparison/match_options/json_resolver.rb +9 -0
data/lib/canon/comparison/match_options/xml_resolver.rb +16 -2
data/lib/canon/comparison/match_options/yaml_resolver.rb +10 -0
data/lib/canon/comparison/match_options.rb +4 -1
data/lib/canon/comparison/whitespace_sensitivity.rb +189 -137
data/lib/canon/comparison/xml_comparator/child_comparison.rb +21 -4
data/lib/canon/comparison/xml_comparator.rb +14 -12
data/lib/canon/comparison/xml_node_comparison.rb +51 -6
data/lib/canon/comparison.rb +52 -9
data/lib/canon/config/env_schema.rb +32 -4
data/lib/canon/config/override_resolver.rb +16 -3
data/lib/canon/config/profile_loader.rb +135 -0
data/lib/canon/config/profiles/metanorma.yml +74 -0
data/lib/canon/config/profiles/metanorma_debug.yml +8 -0
data/lib/canon/config/type_converter.rb +8 -0
data/lib/canon/config.rb +469 -5
data/lib/canon/diff/diff_classifier.rb +41 -11
data/lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb +48 -17
data/lib/canon/diff_formatter/diff_detail_formatter/node_utils.rb +58 -0
data/lib/canon/diff_formatter/diff_detail_formatter.rb +73 -17
data/lib/canon/diff_formatter.rb +493 -36
data/lib/canon/pretty_printer/xml_normalized.rb +395 -0
data/lib/canon/rspec_matchers.rb +36 -0
data/lib/canon/version.rb +1 -1
data/lib/canon/xml/nodes/namespace_node.rb +4 -0
data/lib/canon/xml/nodes/processing_instruction_node.rb +4 -0
data/lib/canon/xml/nodes/root_node.rb +4 -0
data/lib/canon/xml/nodes/text_node.rb +4 -0
data/lib/tasks/performance_helpers.rb +2 -2
metadata +24 -2

data/docs/features/configuration-profiles.adoc ADDED Viewed

@@ -0,0 +1,288 @@
+---
+title: Configuration Profiles
+parent: Features
+nav_order: 7
+---
+= Configuration profiles
+:toc:
+:toclevels: 3
+== Purpose
+Configuration profiles bundle many settings into a single named preset,
+eliminating repetitive configuration blocks across multiple gems.
+Instead of 60+ lines of per-format settings, use one line:
+[source,ruby]
+----
+Canon::Config.instance.profile = :metanorma
+----
+Profiles are defined in YAML files and support inheritance, so a debug
+variant can extend a base profile with only the differences.
+== Built-in profiles
+[cols="1,3"]
+|===
+| Profile | Description
+| `:metanorma`
+| Standard Metanorma spec configuration. Sets preprocessing to `:format`,
+  match profile to `:spec_friendly`, diff algorithm to `:dom`, canonical
+  display format, normalized pretty-print display preprocessing,
+  and XML-specific whitespace element lists.
+| `:metanorma_debug`
+| Extends `:metanorma` with debug output enabled
+  (`show_prettyprint_received: true`).
+|===
+List all available profiles programmatically:
+[source,ruby]
+----
+Canon::Config::ProfileLoader.available_profiles
+# => [:metanorma, :metanorma_debug]
+----
+== Element-level whitespace classification
+The metanorma profile's key feature is its **element-level whitespace classification**.
+This controls how whitespace differences within specific elements are treated:
+**Three-way classification:**
+* **Preserve** (`:preserve`) — Every whitespace character is significant. Use for elements
+  where exact whitespace matters (like `<pre>`, `<code>`).
+* **Collapse** (`:collapse`) — Presence matters but whitespace form doesn't.
+  `"  hello  "` equals `"hello"`. Differences are formatting-only (informative).
+  Use for elements like `<p>`, `<li>`, `<td>` in prose documents.
+* **Strip** (`:strip`) — Whitespace is structural noise, dropped entirely.
+  The default for XML elements not in any list.
+**Metanorma profile element lists:**
+[source,ruby]
+----
+# In metanorma profile
+Canon::Config.instance.profile = :metanorma
+Canon::Config.instance.xml.match.collapse_whitespace_elements
+# => ["p", "title", "name", "td", "th", "dt", "dd", "li", ...]
+Canon::Config.instance.xml.match.preserve_whitespace_elements
+# => ["body", "passthrough"]
+----
+**How it works with `text_content: :normalize`:**
+[source,ruby]
+----
+# With metanorma profile: <p> is in collapse_whitespace_elements
+Canon::Config.instance.profile = :metanorma
+# These are EQUIVALENT (whitespace in <p> is formatting-only)
+Canon::Comparison.equivalent?('<p>  hello  </p>', '<p>hello</p>')
+# => true
+# But <body> is in preserve_whitespace_elements — every character matters
+# These are NOT EQUIVALENT (whitespace in <body> is normative)
+Canon::Comparison.equivalent?('<body>  hello  </body>', '<body>hello</body>')
+# => false
+----
+**Why this matters:**
+In Metanorma/DocBook documents, elements like `<p>`, `<li>`, `<td>` contain prose
+where whitespace formatting (extra spaces, line breaks) is irrelevant. But `<body>`
+or `<passthrough>` contain code or exact whitespace that matters.
+Without element-level classification, you'd have to choose:
+- `text_content: :normalize` — ignores ALL whitespace, too permissive
+- `text_content: :strict` — requires exact match everywhere, too strict
+Element-level classification gives you fine-grained control.
+== Usage
+=== Programmatic (Ruby API)
+Use a **Symbol** for built-in profiles and a **String** for file paths:
+[source,ruby]
+----
+# Built-in profile (Symbol)
+Canon::Config.instance.profile = :metanorma
+# Local YAML file (String)
+Canon::Config.instance.profile = "/path/to/my_profile.yml"
+Canon::Config.instance.profile = "~/my_canon_profile.yml"
+Canon::Config.instance.profile = "config/canon_profile.yml"
+# Or in a configure block
+Canon::Config.configure do |cfg|
+  cfg.profile = :metanorma
+  # Override individual settings after profile if needed
+  cfg.xml.diff.verbose_diff = true
+end
+# Clear the profile (revert to defaults + programmatic values)
+Canon::Config.instance.profile = nil
+----
+IMPORTANT: The type of the value determines how it is resolved:
+**Symbols** are looked up as built-in profile names;
+**Strings** are treated as file paths (with `~` expansion and relative
+path resolution against the working directory).
+Local YAML files can inherit from built-in profiles (see <<inheritance>>).
+=== Environment variable
+Set `CANON_CONFIG_PROFILE` to apply a profile automatically on
+initialization:
+[source,bash]
+----
+# Built-in profile
+CANON_CONFIG_PROFILE=metanorma bundle exec rspec
+# File path
+CANON_CONFIG_PROFILE=~/my_profile.yml bundle exec rspec
+----
+NOTE: `CANON_CONFIG_PROFILE` is distinct from `CANON_PROFILE`, which
+controls the match profile (comparison behavior). The config profile
+controls all settings at once.
+== Priority chain
+With profiles, the resolution chain becomes four layers:
+[source]
+----
++------------------------------------+
+| 1. Environment Variables           | <- Highest Priority
+|    (CANON_XML_DIFF_ALGORITHM)      |
++------------------------------------+
+               | overrides
++------------------------------------+
+| 2. Programmatic Configuration      |
+|    (config.xml.diff.algorithm=)    |
++------------------------------------+
+               | overrides
++------------------------------------+
+| 3. Profile Values                  |
+|    (from YAML profile file)        |
++------------------------------------+
+               | overrides
++------------------------------------+
+| 4. Default Values                  | <- Lowest Priority
+|    (defined in Canon::Config)      |
++------------------------------------+
+----
+This means:
+* ENV variables always win (useful for CI overrides)
+* Programmatic setter calls override profile values
+* Profile values override built-in defaults
+* Clearing the profile (`cfg.profile = nil`) removes only layer 3
+[[inheritance]]
+== Profile inheritance
+A profile can inherit from another using the `inherits` key:
+[source,yaml]
+----
+name: my_debug
+inherits: metanorma
+shared:
+  diff:
+    verbose_diff: true
+    show_prettyprint_received: true
+----
+Inheritance rules:
+* Parent values are loaded first, then child values are deep-merged on top
+* Hashes are merged recursively (child keys override parent keys)
+* Arrays are replaced entirely (not concatenated)
+* Single-parent inheritance only
+* Cycle detection prevents infinite loops
+* Local files can inherit from built-in profiles by name
+== Creating custom profiles
+=== YAML file format
+[source,yaml]
+----
+---
+name: my_profile              # <1>
+description: My custom config # <2>
+inherits: metanorma           # <3>
+shared:                        # <4>
+  preprocessing: format
+  match:
+    profile: spec_friendly
+  diff:
+    algorithm: dom
+    context_lines: 5
+    verbose_diff: false
+formats:                       # <5>
+  xml:
+    match:
+      collapse_whitespace_elements:
+        - p
+        - title
+        - td
+      preserve_whitespace_elements:
+        - body
+        - passthrough
+  html:
+    diff:
+      show_raw_inputs: true
+----
+<1> Profile name (metadata)
+<2> Description (metadata)
+<3> Optional: inherit from another profile (name or path)
+<4> `shared` settings apply to all formats (xml, html, json, yaml, string)
+<5> `formats.<name>` settings override `shared` for that specific format
+=== Attribute mapping
+Profile YAML keys map directly to Canon configuration accessors:
+[cols="2,2"]
+|===
+| YAML path | Ruby equivalent
+| `shared.preprocessing`
+| `cfg.xml.preprocessing = :format`
+| `shared.match.profile`
+| `cfg.xml.match.profile = :spec_friendly`
+| `shared.diff.algorithm`
+| `cfg.xml.diff.algorithm = :dom`
+| `formats.xml.diff.context_lines`
+| `cfg.xml.diff.context_lines = 5`
+|===
+All `DiffConfig` and `MatchConfig` attributes documented in
+link:../reference/options-across-interfaces.adoc[Options Across Interfaces]
+are supported.
+== See also
+* link:environment-configuration/override-system.adoc[Override System] -- ENV variable priority
+* link:match-options/index.adoc[Match Options] -- match profile presets (`:strict`, `:spec_friendly`, etc.)
+* link:../guides/choosing-configuration.adoc[Choosing Configuration] -- decision guide