canon 0.3.27 → 0.3.29

data/docs/features/regenerate-expected.adoc

@@ -0,0 +1,157 @@
+---
+title: Regenerating expected heredocs
+parent: Features
+nav_order: 50
+---
+= Regenerating expected heredocs
+:toc:
+:toclevels: 3
+
+== Purpose
+
+When a Canon matcher (`be_xml_equivalent_to`, `be_html_equivalent_to`, etc.)
+asserts equivalence against a heredoc-literal `expected`, and the
+upstream code legitimately changes its output, the fixture heredoc
+needs to be updated to the new value. The default workflow is:
+
+1. Run `bundle exec rspec` — see N failing assertions.
+2. Copy the prettyprinted received from canon's diff display.
+3. Paste into the `<<~XML ... XML` heredoc in the spec file.
+4. Re-run, iterate.
+
+For large fixture suites (e.g. the metanorma stack — 200+ heredocs per
+rebaseline event) this is slow and error-prone (indent drift, partial
+copies, missed trailing whitespace).
+
+The `CANON_REGENERATE_EXPECTED=true` env var collapses steps 2-3 into
+an automated rewrite.
+
+== Workflow
+
+[source,sh]
+----
+CANON_REGENERATE_EXPECTED=true bundle exec rspec
+git diff           # review what changed
+git commit -am "rebaseline fixtures after upstream X change"
+----
+
+When the env var is set:
+
+* Every failing `be_*_equivalent_to` assertion attempts to rewrite the
+  source heredoc that backs its `expected` argument.
+* The rewrite uses the same `Canon::PrettyPrinter` that powers
+  `CANON_<FORMAT>_DIFF_SHOW_PRETTYPRINT_RECEIVED` — output is identical
+  to what would have appeared in the diff display.
+* Successful rewrites mark the assertion as passing for the run, so CI
+  does not fail mid-rebaseline.
+* Passing assertions are never touched.
+* Negated matchers (`.not_to`) are never rewritten.
+
+Each rewrite (or skip) emits a single-line log to stderr:
+
+[source]
+----
+[canon:rebaseline] rewritten /path/to/spec.rb:123
+[canon:rebaseline] skipped_interpolation /path/to/spec.rb:456
+----
+
+== Supported expected forms (v1)
+
+The rebaseliner uses Prism to parse the caller spec file and locate the
+heredoc backing the `expected` argument. It supports:
+
+* `<<~XML` / `<<-XML` / `<<XML` heredoc assigned to a local variable in
+  the same `it` block.
+* `<<~XML` / `<<-XML` / `<<XML` heredoc passed inline directly to the
+  matcher.
+* *Multiple sequential assignments* to the same local variable within
+  one `it` block (the common metanorma pattern of reassigning `output`
+  before each format-specific expect). The rebaseliner walks backward
+  from the failing `expect` line to the *most-recent* assignment and
+  rewrites that one.
+* Substitution chains on the actual side (e.g.
+  `expect(strip_guid(actual).gsub(...))`) — since the matcher receives
+  the post-substitution value, idempotency holds on the next run.
+
+== Skipped with a warning (v1)
+
+* Heredoc with `#{}` interpolation. Mechanical rewriting would lose
+  the interpolation; v2 (token preservation) is planned.
+* Expected value from a method call (`load_fixture(...)`). The
+  expected is computed at runtime; the rebaseliner cannot identify
+  which on-disk fixture to rewrite.
+* Expected value from a `let` or `shared_context` in a different
+  spec/support file. v1 does not cross file boundaries.
+* Inline string literal expected (no heredoc). There is nothing to
+  re-indent into.
+
+In each skipped case the file is left unchanged and the assertion
+fails normally with the standard Canon diff display.
+
+== Tracking line shifts across multiple rewrites
+
+After a rewrite, the file's on-disk line numbering can shift if the new
+heredoc body has a different line count from the old. Ruby's
+`caller_locations` continues to report the *original* line numbers
+during the same process run (the in-memory source is unchanged), so
+the rebaseliner maintains a per-file cumulative line-shift tracker and
+translates subsequent caller-reported lines accordingly. Multiple
+rewrites within a single `it` block, or across multiple `it` blocks
+in the same spec file, work transparently.
+
+== Limitations and v2 roadmap
+
+The following are intentionally out of v1 scope:
+
+* `#{}` interpolation in heredoc bodies — v2 adds token-preserving
+  rewrites that re-anchor `#{var}` fragments in the prettyprinted
+  actual.
+* JSON and YAML format prettyprinter wiring (v1 covers XML + HTML).
+* A `canon regenerate SPEC_GLOB` Thor subcommand with a summary
+  report.
+* File-locking for `parallel_rspec` safety. v1 documents "do not run
+  rebaseline mode in parallel."
+* Optional `rubocop -A` post-rewrite formatter.
+
+== Architecture
+
+The rebaseliner is a self-contained module under
+`lib/canon/rebaseliner/`:
+
+`Canon::Rebaseliner`::
+  Top-level orchestrator. `enabled?` reads the env var.
+  `rewrite!` is the entry called by the matcher hook on failure.
+
+`CallSiteResolver`::
+  Parses the spec file with Prism and locates the matcher invocation
+  on the failing line. Returns the AST node passed as `expected` and
+  the enclosing `it`/`example` block.
+
+`HeredocLocator`::
+  Classifies the `expected` AST node. For local-variable references,
+  walks the enclosing block backward to find the most-recent
+  assignment. Returns a `HeredocSpec` describing the byte range to
+  rewrite, or a skip reason.
+
+`HeredocRewriter`::
+  Re-indents the new body for `<<~` (squiggly) heredocs and writes the
+  new source via `AtomicWriter`.
+
+`AtomicWriter`::
+  Tempfile-then-rename to avoid half-written files on Ctrl-C.
+
+`Logger`::
+  Single-line stderr writes with the `[canon:rebaseline]` prefix.
+
+The matcher hook lives in `lib/canon/rspec_matchers.rb`. It captures
+`caller_locations` only when the env var is set, so passing
+assertions pay no overhead.
+
+== Testing the rebaseliner
+
+`spec/canon/rebaseliner_spec.rb` runs each fixture under
+`spec/fixtures/rebaseliner/` in a subprocess with the env var set,
+then asserts the file content was (or was not) modified appropriately
+and that the stderr log line is present. Add new fixture cases by
+dropping `*_input.rb` into `spec/fixtures/rebaseliner/` and a new
+example into `rebaseliner_spec.rb`.

data/docs/guides/choosing-configuration.adoc

@@ -216,7 +216,7 @@ Canon::Comparison.equivalent?(doc1, doc2,
 )
 ----
 
-**Remember**: Match options behave differently with each algorithm! See link:../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior].
+**Remember**: Match options behave differently with each algorithm! See link:../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior].
 
 ==== Whitespace Type Sensitivity
 
@@ -709,14 +709,14 @@ Profiles bundle all layers (preprocessing, match profile, diff settings,
 whitespace element lists) into a named preset defined in YAML.
 Custom file profiles can inherit from built-in profiles.
 
-See link:../features/configuration-profiles.adoc[Configuration Profiles] for full documentation.
+See link:../../features/configuration-profiles/[Configuration Profiles] for full documentation.
 
 == See Also
 
-* link:../features/configuration-profiles.adoc[Configuration Profiles] - Named config presets
-* link:../understanding/comparison-pipeline.adoc[Comparison Pipeline] - Understanding the 4 layers
+* link:../../features/configuration-profiles/[Configuration Profiles] - Named config presets
+* link:../../understanding/comparison-pipeline/[Comparison Pipeline] - Understanding the 4 layers
 * link:../understanding/algorithms/[Algorithms] - Detailed algorithm documentation
-* link:../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] - How algorithms differ
-* link:../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output] - Output format differences
+* link:../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior] - How algorithms differ
+* link:../../features/diff-formatting/algorithm-specific-output/[Algorithm-Specific Output] - Output format differences
 * link:../features/match-options/[Match Options] - All matching options
 * link:../features/diff-formatting/[Diff Formatting] - Formatting options

data/docs/interfaces/rspec/index.adoc

@@ -428,7 +428,7 @@ IMPORTANT: Display filtering does NOT affect equivalence determination. It
 only controls which differences appear in the failure output. Equivalence is
 always based on normative differences only.
 
-See link:../../features/diff-formatting/display-filtering.adoc[Display
+See link:../../features/diff-formatting/display-filtering/[Display
 filtering] for complete details.
 
 == Diff algorithms

data/docs/interfaces/ruby-api/index.adoc

@@ -545,7 +545,7 @@ result = Canon::Comparison.equivalent?(xml1, xml2,
 ----
 ====
 
-See link:../../features/diff-formatting/display-filtering.adoc[Display
+See link:../../features/diff-formatting/display-filtering/[Display
 filtering] for complete details.
 
 === Format-specific comparators

data/docs/internals/diffnode-enrichment.adoc

@@ -606,7 +606,7 @@ The old API still works for backwards compatibility, but enriched properties pro
 
 == See also
 
-* link:../understanding/architecture.adoc[Architecture] - 4-layer architecture overview
+* link:../../understanding/architecture/[Architecture] - 4-layer architecture overview
 * link:../understanding/algorithms/[Algorithms] - DOM and Semantic algorithm details
 * link:../features/diff-formatting/[Diff Formatting] - Layer 4 rendering options
 * link:diff-char-range-pipeline[DiffCharRange Pipeline] - How enriched DiffNodes are processed into character-level display positions

data/docs/internals/index.adoc

@@ -71,7 +71,7 @@ Canon separates comparison concerns into four layers:
 
 Only Layer 2 differs between algorithms, and the enriched DiffNode structure ensures clean communication between layers.
 
-See link:../understanding/architecture.adoc[Architecture] for the complete overview.
+See link:../understanding/architecture/[Architecture] for the complete overview.
 
 === Enriched Metadata Flow
 
@@ -265,7 +265,7 @@ def add_difference(node1, node2, diff1, diff2, dimension, opts, differences)
 end
 ----
 
-See link:../understanding/algorithms/dom-diff.adoc[DOM Diff Algorithm] for details.
+See link:../understanding/algorithms/dom-diff/[DOM Diff Algorithm] for details.
 
 === Semantic Algorithm
 
@@ -289,11 +289,11 @@ def convert_insert(operation)
 end
 ----
 
-See link:../understanding/algorithms/semantic-tree-diff.adoc[Semantic Tree Diff Algorithm] for details.
+See link:../understanding/algorithms/semantic-tree-diff/[Semantic Tree Diff Algorithm] for details.
 
 == See Also
 
-* link:../understanding/architecture.adoc[Architecture] - 4-layer architecture overview
+* link:../understanding/architecture/[Architecture] - 4-layer architecture overview
 * link:../understanding/algorithms/[Algorithms] - DOM and Semantic algorithm details
 * link:../features/diff-formatting/[Diff Formatting] - Layer 4 rendering options
 * link:../advanced/[Advanced Topics] - Deep technical documentation

data/docs/reference/cli-options.adoc

@@ -11,9 +11,9 @@ nav_order: 1
 
 This page provides a complete reference for all Canon command-line interface options organized by command and function.
 
-For conceptual understanding, see link:../understanding/comparison-pipeline.adoc[Comparison Pipeline].
+For conceptual understanding, see link:../../understanding/comparison-pipeline/[Comparison Pipeline].
 
-For choosing the right configuration, see link:../guides/choosing-configuration.adoc[Choosing Configuration].
+For choosing the right configuration, see link:../../guides/choosing-configuration/[Choosing Configuration].
 
 == Command syntax
 
@@ -413,8 +413,8 @@ canon diff page1.html page2.html \
 
 == See also
 
-* link:../understanding/comparison-pipeline.adoc[Comparison Pipeline] - 4-layer architecture
-* link:../guides/choosing-configuration.adoc[Choosing Configuration] - Decision guide
+* link:../../understanding/comparison-pipeline/[Comparison Pipeline] - 4-layer architecture
+* link:../../guides/choosing-configuration/[Choosing Configuration] - Decision guide
 * link:../features/match-options/[Match Options] - Dimension reference
 * link:../features/diff-formatting/[Diff Formatting] - Output customization
 * link:../interfaces/cli/[CLI Interface] - Command-line usage guide

data/docs/reference/environment-variables.adoc

@@ -128,7 +128,7 @@ export CANON_JSON_FORMAT_PREPROCESSING=normalize
 |`CANON_XML_DIFF_PRETTY_PRINTED_EXPECTED`
 |boolean
 |`false`
-|When `true`, whitespace-only text nodes that start with `"\n"` inside `:collapse`-classified elements are dropped from the **expected (fixture)** document before it reaches the line diff.  Solves the asymmetric case where the expected side is a hand-indented heredoc fixture but the received side is compact programmatic XML.  Only applies when `display_preprocessing: :normalize_pretty_print`.  Format-specific; no global form.  See also link:../features/match-options/pretty-printed-fixtures.adoc[Pretty-printed fixture support].
+|When `true`, whitespace-only text nodes that start with `"\n"` inside `:collapse`-classified elements are dropped from the **expected (fixture)** document before it reaches the line diff.  Solves the asymmetric case where the expected side is a hand-indented heredoc fixture but the received side is compact programmatic XML.  Only applies when `display_preprocessing: :normalize_pretty_print`.  Format-specific; no global form.  See also link:../../features/match-options/pretty-printed-fixtures/[Pretty-printed fixture support].
 |XML (display only)
 
 |`CANON_XML_DIFF_PRETTY_PRINTED_RECEIVED`

data/docs/understanding/algorithms/dom-diff.adoc

@@ -174,7 +174,7 @@ Canon::Comparison.equivalent?(doc1, doc2,
 )
 ----
 
-See link:../../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] for how DOM interprets match options.
+See link:../../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior] for how DOM interprets match options.
 
 === With Diff Formatting
 
@@ -289,7 +289,7 @@ The DOM algorithm cannot detect when content moves to a different position:
 
 **Limitation**: Reordered content shows as DELETE + INSERT pairs
 
-**Workaround**: Use link:semantic-tree-diff.adoc[Semantic Algorithm] for move detection
+**Workaround**: Use link:../semantic-tree-diff/[Semantic Algorithm] for move detection
 
 === Position-Dependent
 
@@ -297,7 +297,7 @@ The algorithm assumes similar structure between documents:
 
 **Limitation**: Heavily restructured documents produce noisy diffs
 
-**Workaround**: Use link:semantic-tree-diff.adoc[Semantic Algorithm] for restructured documents
+**Workaround**: Use link:../semantic-tree-diff/[Semantic Algorithm] for restructured documents
 
 == Common Use Cases
 
@@ -381,9 +381,9 @@ Canon::Comparison.equivalent?(html1, html2,
 
 == See Also
 
-* link:index.adoc[Algorithms Overview] - Comparison of DOM vs Semantic
-* link:semantic-tree-diff.adoc[Semantic Algorithm] - Alternative algorithm
-* link:../../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] - How DOM interprets options
-* link:../../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output] - Output format details
-* link:../../guides/choosing-configuration.adoc[Choosing Configuration] - Complete decision guide
-* link:../../advanced/dom-diff-internals.adoc[DOM Diff Internals] - Advanced implementation details (if available)
+* link:../[Algorithms Overview] - Comparison of DOM vs Semantic
+* link:../semantic-tree-diff/[Semantic Algorithm] - Alternative algorithm
+* link:../../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior] - How DOM interprets options
+* link:../../../features/diff-formatting/algorithm-specific-output/[Algorithm-Specific Output] - Output format details
+* link:../../../guides/choosing-configuration/[Choosing Configuration] - Complete decision guide
+* link:../dom-diff/[DOM Diff] - Implementation details

data/docs/understanding/algorithms/index.adoc

@@ -12,7 +12,7 @@ has_children: true
 
 Canon provides two comparison algorithms, each with different strengths and use cases. This section explains how to choose between them and what to expect from each.
 
-This corresponds to **Layer 2 (Algorithm Selection)** in Canon's 4-layer architecture. See link:../comparison-pipeline.adoc[Comparison Pipeline] for the complete flow.
+This corresponds to **Layer 2 (Algorithm Selection)** in Canon's 4-layer architecture. See link:../comparison-pipeline/[Comparison Pipeline] for the complete flow.
 
 == Overview
 
@@ -21,12 +21,12 @@ Canon supports two algorithms for document comparison:
 * **DOM Algorithm** - Fast, stable, positional comparison (default)
 * **Semantic Algorithm** - Slower, intelligent, detects moves and restructuring (experimental)
 
-**Critical**: The algorithm choice affects how Layers 3 and 4 behave. See link:../../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] and link:../../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output].
+**Critical**: The algorithm choice affects how Layers 3 and 4 behave. See link:../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior] and link:../../features/diff-formatting/algorithm-specific-output/[Algorithm-Specific Output].
 
 == Child Pages
 
-* link:dom-diff.adoc[DOM Algorithm] - Positional comparison details
-* link:semantic-tree-diff.adoc[Semantic Algorithm] - Tree-based comparison details
+* link:dom-diff/[DOM Algorithm] - Positional comparison details
+* link:semantic-tree-diff/[Semantic Algorithm] - Tree-based comparison details
 
 == Algorithm Comparison
 
@@ -249,7 +249,7 @@ NOTE: These are approximate times. Actual performance depends on document struct
 3. Performance slower but more intelligent
 4. Output format changes to operation-based
 
-See link:../../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] for migration details.
+See link:../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior] for migration details.
 
 === Switching from Semantic to DOM
 
@@ -306,9 +306,9 @@ end
 
 == See also
 
-* link:dom-diff.adoc[DOM Algorithm] - Detailed DOM algorithm documentation
-* link:semantic-tree-diff.adoc[Semantic Algorithm] - Detailed semantic algorithm documentation
-* link:../comparison-pipeline.adoc[Comparison Pipeline] - 4-layer architecture
-* link:../../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] - How algorithms interpret options
-* link:../../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output] - Output format differences
-* link:../../guides/choosing-configuration.adoc[Choosing Configuration] - Complete decision guide
+* link:dom-diff/[DOM Algorithm] - Detailed DOM algorithm documentation
+* link:semantic-tree-diff/[Semantic Algorithm] - Detailed semantic algorithm documentation
+* link:../comparison-pipeline/[Comparison Pipeline] - 4-layer architecture
+* link:../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior] - How algorithms interpret options
+* link:../../features/diff-formatting/algorithm-specific-output/[Algorithm-Specific Output] - Output format differences
+* link:../../guides/choosing-configuration/[Choosing Configuration] - Complete decision guide

data/docs/understanding/algorithms/semantic-tree-diff.adoc

@@ -230,7 +230,7 @@ Canon::Comparison.equivalent?(doc1, doc2,
 )
 ----
 
-See link:../../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] for details.
+See link:../../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior] for details.
 
 === With Diff Formatting
 
@@ -525,9 +525,9 @@ When switching from DOM to Semantic:
 
 == See Also
 
-* link:index.adoc[Algorithms Overview] - Comparison of DOM vs Semantic
-* link:dom-diff.adoc[DOM Algorithm] - Standard algorithm
-* link:../../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] - How Semantic interprets options
-* link:../../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output] - Output format details
-* link:../../guides/choosing-configuration.adoc[Choosing Configuration] - Complete decision guide
-* link:../../advanced/semantic-tree-diff-internals.adoc[Semantic Tree Diff Internals] - Advanced details (if available)
+* link:../[Algorithms Overview] - Comparison of DOM vs Semantic
+* link:../dom-diff/[DOM Algorithm] - Standard algorithm
+* link:../../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior] - How Semantic interprets options
+* link:../../../features/diff-formatting/algorithm-specific-output/[Algorithm-Specific Output] - Output format details
+* link:../../../guides/choosing-configuration/[Choosing Configuration] - Complete decision guide
+* link:../semantic-tree-diff/[Semantic Tree Diff] - Advanced details

data/docs/understanding/architecture.adoc

@@ -11,9 +11,9 @@ nav_order: 1
 
 This document explains Canon's 4-layer comparison architecture and how documents flow through preprocessing, algorithm selection, semantic matching, and diff rendering.
 
-For a guided walkthrough of choosing configurations, see link:../guides/choosing-configuration.adoc[Choosing Configuration].
+For a guided walkthrough of choosing configurations, see link:../../guides/choosing-configuration/[Choosing Configuration].
 
-For detailed 4-layer pipeline documentation, see link:comparison-pipeline.adoc[Comparison Pipeline].
+For detailed 4-layer pipeline documentation, see link:../comparison-pipeline/[Comparison Pipeline].
 
 == Overview
 
@@ -799,7 +799,7 @@ Control how differences are displayed. **This layer is algorithm-specific** - ea
 * **DOM algorithm**: Generates line-based differences
 * **Semantic algorithm**: Generates operation-based differences (INSERT, DELETE, UPDATE, MOVE)
 
-See link:../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output] for detailed comparison.
+See link:../../features/diff-formatting/algorithm-specific-output/[Algorithm-Specific Output] for detailed comparison.
 
 === Diff options
 
@@ -865,7 +865,7 @@ result = Canon::Comparison.equivalent?(doc1, doc2,
 )
 ----
 
-See link:comparison-pipeline.adoc[Comparison Pipeline] for layer-by-layer examples.
+See link:../comparison-pipeline/[Comparison Pipeline] for layer-by-layer examples.
 
 === DiffNode: Representation of differences
 
@@ -1153,16 +1153,16 @@ This refactoring improves:
 
 == See also
 
-* link:comparison-pipeline.adoc[Comparison Pipeline] - Complete 4-layer walkthrough
+* link:../comparison-pipeline/[Comparison Pipeline] - Complete 4-layer walkthrough
 * link:algorithms/[Algorithms] - DOM and Semantic algorithm details
 * link:../internals/[Internals] - Implementation details and data structures
-* link:../internals/diffnode-enrichment.adoc[DiffNode Enrichment] - How metadata flows from Layer 2 to Layer 4
+* link:../../internals/diffnode-enrichment/[DiffNode Enrichment] - How metadata flows from Layer 2 to Layer 4
 * link:../features/preprocessing/[Preprocessing options]
 * link:../features/match-options/[Match dimensions and profiles]
-* link:../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior]
+* link:../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior]
 * link:../features/diff-formatting/[Diff formatting]
-* link:../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output]
-* link:../guides/choosing-configuration.adoc[Choosing Configuration]
+* link:../../features/diff-formatting/algorithm-specific-output/[Algorithm-Specific Output]
+* link:../../guides/choosing-configuration/[Choosing Configuration]
 * link:../interfaces/ruby-api/[Ruby API documentation]
 * link:../interfaces/cli/[Command-line interface]
 * link:../interfaces/rspec/[RSpec matchers]

data/docs/understanding/comparison-pipeline.adoc

@@ -67,7 +67,7 @@ graph TD
 * Match profiles (preset combinations)
 * Algorithm-specific behaviors
 
-**Documentation**: See link:../features/match-options/[Match Options] and link:../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior]
+**Documentation**: See link:../features/match-options/[Match Options] and link:../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior]
 
 === Layer 4: Diff Formatting
 
@@ -81,7 +81,7 @@ graph TD
 * Context and grouping
 * Character visualization
 
-**Documentation**: See link:../features/diff-formatting/[Diff Formatting] and link:../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output]
+**Documentation**: See link:../features/diff-formatting/[Diff Formatting] and link:../../features/diff-formatting/algorithm-specific-output/[Algorithm-Specific Output]
 
 == DiffNode Data Flow
 
@@ -154,7 +154,7 @@ After creation, DiffNodes are enriched with metadata for Layer 4 rendering:
 * **NodeSerializer**: Library-agnostic serialization of node content
 * **Attribute extraction**: Normalized attribute hashes
 
-See link:../internals/diffnode-enrichment.adoc[DiffNode Enrichment] for implementation details.
+See link:../../internals/diffnode-enrichment/[DiffNode Enrichment] for implementation details.
 
 === Layer 3: Classification
 
@@ -432,8 +432,8 @@ Canon::Comparison.equivalent?(doc1, doc2,
 
 == See Also
 
-* link:architecture.adoc[Architecture] - Overall system design
+* link:../architecture/[Architecture] - Overall system design
 * link:algorithms/[Algorithms] - Detailed algorithm documentation
-* link:../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] - How algorithms interpret match options
-* link:../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output] - Different output formats
-* link:../guides/choosing-configuration.adoc[Choosing Configuration] - Decision guide for all layers
+* link:../../features/match-options/algorithm-specific-behavior/[Algorithm-Specific Behavior] - How algorithms interpret match options
+* link:../../features/diff-formatting/algorithm-specific-output/[Algorithm-Specific Output] - Different output formats
+* link:../../guides/choosing-configuration/[Choosing Configuration] - Decision guide for all layers

data/docs/understanding/formats/html.adoc

@@ -396,9 +396,9 @@ XHTML is treated as XML and follows stricter rules.
 
 == See also
 
-* link:../comparison-pipeline.adoc[Comparison Pipeline] - Understanding the 4 layers
+* link:../../comparison-pipeline/[Comparison Pipeline] - Understanding the 4 layers
 * link:../../features/match-options/[Match Options] - All matching options
-* link:../../guides/choosing-configuration.adoc[Choosing Configuration] - Decision guide
-* link:index.adoc[Format Support] - Overview of all formats
-* link:xml.adoc[XML Format] - XML-specific features
-* link:json.adoc[JSON Format] - JSON-specific features
+* link:../../../guides/choosing-configuration/[Choosing Configuration] - Decision guide
+* link:../[Format Support] - Overview of all formats
+* link:../xml/[XML Format] - XML-specific features
+* link:../json/[JSON Format] - JSON-specific features

data/docs/understanding/formats/index.adoc

@@ -20,10 +20,10 @@ Canon provides unified canonicalization and comparison for four serialization fo
 
 This page provides an overview of format support. See the child pages for format-specific details:
 
-* link:xml.adoc[XML Format] - W3C C14N, namespace handling
-* link:html.adoc[HTML Format] - HTML4/5 detection, rendering behavior
-* link:json.adoc[JSON Format] - Sorted keys, type preservation
-* link:yaml.adoc[YAML Format] - YAML specifics, anchors and aliases
+* link:xml/[XML Format] - W3C C14N, namespace handling
+* link:html/[HTML Format] - HTML4/5 detection, rendering behavior
+* link:json/[JSON Format] - Sorted keys, type preservation
+* link:yaml/[YAML Format] - YAML specifics, anchors and aliases
 
 == Format detection
 
@@ -257,5 +257,5 @@ Canon::Comparison::YamlComparator.equivalent?(yaml1, yaml2,
 * link:../../interfaces/ruby-api/[Ruby API documentation]
 * link:../../interfaces/cli/[Command-line interface]
 * link:../../features/match-options/[Match options reference]
-* link:../comparison-pipeline.adoc[Comparison Pipeline]
+* link:../comparison-pipeline/[Comparison Pipeline]
 * link:../../features/preprocessing/[Preprocessing options]

data/docs/understanding/formats/json.adoc

@@ -382,9 +382,9 @@ Canon normalizes Unicode escapes during canonicalization.
 
 == See also
 
-* link:../comparison-pipeline.adoc[Comparison Pipeline] - Understanding the 4 layers
+* link:../../comparison-pipeline/[Comparison Pipeline] - Understanding the 4 layers
 * link:../../features/match-options/[Match Options] - All matching options
-* link:../../guides/choosing-configuration.adoc[Choosing Configuration] - Decision guide
-* link:index.adoc[Format Support] - Overview of all formats
-* link:yaml.adoc[YAML Format] - YAML-specific features (similar to JSON)
-* link:xml.adoc[XML Format] - XML-specific features
+* link:../../../guides/choosing-configuration/[Choosing Configuration] - Decision guide
+* link:../[Format Support] - Overview of all formats
+* link:../yaml/[YAML Format] - YAML-specific features (similar to JSON)
+* link:../xml/[XML Format] - XML-specific features

data/docs/understanding/formats/xml.adoc

@@ -439,8 +439,8 @@ canon diff expected.xml actual.xml \
 
 == See also
 
-* link:../comparison-pipeline.adoc[Comparison Pipeline] - Understanding the 4 layers
+* link:../../comparison-pipeline/[Comparison Pipeline] - Understanding the 4 layers
 * link:../../features/match-options/[Match Options] - All matching options
-* link:../../guides/choosing-configuration.adoc[Choosing Configuration] - Decision guide
-* link:index.adoc[Format Support] - Overview of all formats
-* link:html.adoc[HTML Format] - HTML-specific features
+* link:../../../guides/choosing-configuration/[Choosing Configuration] - Decision guide
+* link:../[Format Support] - Overview of all formats
+* link:../html/[HTML Format] - HTML-specific features

data/docs/understanding/formats/yaml.adoc

@@ -496,9 +496,9 @@ YAML is sensitive to indentation. Use `structural_whitespace: :ignore` to handle
 
 == See also
 
-* link:../comparison-pipeline.adoc[Comparison Pipeline] - Understanding the 4 layers
+* link:../../comparison-pipeline/[Comparison Pipeline] - Understanding the 4 layers
 * link:../../features/match-options/[Match Options] - All matching options
-* link:../../guides/choosing-configuration.adoc[Choosing Configuration] - Decision guide
-* link:index.adoc[Format Support] - Overview of all formats
-* link:json.adoc[JSON Format] - JSON-specific features (similar to YAML)
-* link:xml.adoc[XML Format] - XML-specific features
+* link:../../../guides/choosing-configuration/[Choosing Configuration] - Decision guide
+* link:../[Format Support] - Overview of all formats
+* link:../json/[JSON Format] - JSON-specific features (similar to YAML)
+* link:../xml/[XML Format] - XML-specific features

data/lib/canon/comparison/diff_node_builder.rb

@@ -179,6 +179,15 @@ module Canon
           return "whitespace: #{describe_whitespace(text1)} vs #{describe_whitespace(text2)}"
         end
 
+        # Identical content modulo whitespace: two full visualized
+        # copies read as materially different text when the only
+        # delta is trailing/invisible whitespace (#94) — the compact
+        # character-count description says what actually differs.
+        if text1.strip == text2.strip
+          return "whitespace-only: #{describe_whitespace(text1)} vs " \
+                 "#{describe_whitespace(text2)}"
+        end
+
         "Text: \"#{visualize_whitespace(text1)}\" vs \"#{visualize_whitespace(text2)}\""
       end
 

data/lib/canon/config/env_schema.rb

@@ -21,6 +21,12 @@ module Canon
 
       FORMAT_ATTRIBUTE_TYPES = {
         preprocessing: :string,
+
+        # Rebaseliner: opt-in mode that rewrites failing heredoc
+        # expectations in spec files with the prettyprinted received
+        # value. Read directly by Canon::Rebaseliner.enabled?; schema
+        # entry exists for --env-help discoverability.
+        regenerate_expected: :boolean,
       }.freeze
 
       class << self