RubyGems - canon - Versions diffs - 0.1.6 → 0.1.7 - Mend

canon 0.1.6 → 0.1.7

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 (136) hide show

checksums.yaml +4 -4
data/.rubocop_todo.yml +163 -67
data/README.adoc +400 -7
data/docs/Gemfile +9 -0
data/docs/INDEX.adoc +99 -182
data/docs/_config.yml +100 -0
data/docs/advanced/diff-classification.adoc +547 -0
data/docs/advanced/diff-pipeline.adoc +358 -0
data/docs/advanced/index.adoc +214 -0
data/docs/advanced/semantic-diff-report.adoc +390 -0
data/docs/{VERBOSE.adoc → advanced/verbose-mode-architecture.adoc} +51 -53
data/docs/features/diff-formatting/algorithm-specific-output.adoc +533 -0
data/docs/{CHARACTER_VISUALIZATION.adoc → features/diff-formatting/character-visualization.adoc} +23 -62
data/docs/features/diff-formatting/colors-and-symbols.adoc +606 -0
data/docs/features/diff-formatting/context-and-grouping.adoc +490 -0
data/docs/features/diff-formatting/display-filtering.adoc +472 -0
data/docs/features/diff-formatting/index.adoc +140 -0
data/docs/features/environment-configuration/index.adoc +327 -0
data/docs/features/environment-configuration/override-system.adoc +436 -0
data/docs/features/environment-configuration/size-limits.adoc +273 -0
data/docs/features/index.adoc +173 -0
data/docs/features/input-validation/index.adoc +521 -0
data/docs/features/match-options/algorithm-specific-behavior.adoc +365 -0
data/docs/features/match-options/html-policies.adoc +312 -0
data/docs/features/match-options/index.adoc +621 -0
data/docs/getting-started/index.adoc +83 -0
data/docs/getting-started/quick-start.adoc +76 -0
data/docs/guides/choosing-configuration.adoc +689 -0
data/docs/guides/index.adoc +181 -0
data/docs/{CLI.adoc → interfaces/cli/index.adoc} +18 -13
data/docs/interfaces/index.adoc +101 -0
data/docs/{RSPEC.adoc → interfaces/rspec/index.adoc} +242 -31
data/docs/{RUBY_API.adoc → interfaces/ruby-api/index.adoc} +118 -16
data/docs/lychee.toml +65 -0
data/docs/reference/cli-options.adoc +418 -0
data/docs/reference/environment-variables.adoc +375 -0
data/docs/reference/index.adoc +204 -0
data/docs/reference/options-across-interfaces.adoc +417 -0
data/docs/understanding/algorithms/dom-diff.adoc +389 -0
data/docs/understanding/algorithms/index.adoc +314 -0
data/docs/understanding/algorithms/semantic-tree-diff.adoc +533 -0
data/docs/understanding/architecture.adoc +447 -0
data/docs/understanding/comparison-pipeline.adoc +317 -0
data/docs/understanding/formats/html.adoc +380 -0
data/docs/understanding/formats/index.adoc +261 -0
data/docs/understanding/formats/json.adoc +390 -0
data/docs/understanding/formats/xml.adoc +366 -0
data/docs/understanding/formats/yaml.adoc +504 -0
data/docs/understanding/index.adoc +130 -0
data/lib/canon/cli.rb +42 -1
data/lib/canon/commands/diff_command.rb +108 -23
data/lib/canon/comparison/compare_profile.rb +101 -0
data/lib/canon/comparison/comparison_result.rb +41 -2
data/lib/canon/comparison/html_comparator.rb +292 -71
data/lib/canon/comparison/html_compare_profile.rb +117 -0
data/lib/canon/comparison/match_options.rb +42 -4
data/lib/canon/comparison/strategies/base_match_strategy.rb +99 -0
data/lib/canon/comparison/strategies/match_strategy_factory.rb +74 -0
data/lib/canon/comparison/strategies/semantic_tree_match_strategy.rb +220 -0
data/lib/canon/comparison/xml_comparator.rb +695 -91
data/lib/canon/comparison.rb +207 -2
data/lib/canon/config/env_provider.rb +71 -0
data/lib/canon/config/env_schema.rb +58 -0
data/lib/canon/config/override_resolver.rb +55 -0
data/lib/canon/config/type_converter.rb +59 -0
data/lib/canon/config.rb +158 -29
data/lib/canon/data_model.rb +29 -0
data/lib/canon/diff/diff_classifier.rb +74 -14
data/lib/canon/diff/diff_context_builder.rb +41 -0
data/lib/canon/diff/diff_line.rb +18 -2
data/lib/canon/diff/diff_node.rb +18 -3
data/lib/canon/diff/diff_node_mapper.rb +71 -12
data/lib/canon/diff/formatting_detector.rb +53 -0
data/lib/canon/diff_formatter/by_line/base_formatter.rb +60 -5
data/lib/canon/diff_formatter/by_line/html_formatter.rb +68 -16
data/lib/canon/diff_formatter/by_line/json_formatter.rb +0 -37
data/lib/canon/diff_formatter/by_line/simple_formatter.rb +0 -42
data/lib/canon/diff_formatter/by_line/xml_formatter.rb +116 -31
data/lib/canon/diff_formatter/by_line/yaml_formatter.rb +0 -37
data/lib/canon/diff_formatter/by_object/base_formatter.rb +126 -19
data/lib/canon/diff_formatter/by_object/xml_formatter.rb +30 -1
data/lib/canon/diff_formatter/debug_output.rb +7 -1
data/lib/canon/diff_formatter/diff_detail_formatter.rb +674 -57
data/lib/canon/diff_formatter/legend.rb +42 -0
data/lib/canon/diff_formatter.rb +78 -9
data/lib/canon/errors.rb +56 -0
data/lib/canon/formatters/html_formatter_base.rb +35 -1
data/lib/canon/formatters/json_formatter.rb +3 -0
data/lib/canon/formatters/yaml_formatter.rb +3 -0
data/lib/canon/html/data_model.rb +229 -0
data/lib/canon/html.rb +9 -0
data/lib/canon/options/cli_generator.rb +70 -0
data/lib/canon/options/registry.rb +234 -0
data/lib/canon/rspec_matchers.rb +34 -13
data/lib/canon/tree_diff/adapters/html_adapter.rb +316 -0
data/lib/canon/tree_diff/adapters/json_adapter.rb +204 -0
data/lib/canon/tree_diff/adapters/xml_adapter.rb +285 -0
data/lib/canon/tree_diff/adapters/yaml_adapter.rb +213 -0
data/lib/canon/tree_diff/core/attribute_comparator.rb +84 -0
data/lib/canon/tree_diff/core/matching.rb +241 -0
data/lib/canon/tree_diff/core/node_signature.rb +164 -0
data/lib/canon/tree_diff/core/node_weight.rb +135 -0
data/lib/canon/tree_diff/core/tree_node.rb +450 -0
data/lib/canon/tree_diff/matchers/hash_matcher.rb +258 -0
data/lib/canon/tree_diff/matchers/similarity_matcher.rb +168 -0
data/lib/canon/tree_diff/matchers/structural_propagator.rb +242 -0
data/lib/canon/tree_diff/matchers/universal_matcher.rb +220 -0
data/lib/canon/tree_diff/operation_converter.rb +631 -0
data/lib/canon/tree_diff/operations/operation.rb +92 -0
data/lib/canon/tree_diff/operations/operation_detector.rb +626 -0
data/lib/canon/tree_diff/tree_diff_integrator.rb +140 -0
data/lib/canon/tree_diff.rb +33 -0
data/lib/canon/validators/json_validator.rb +3 -1
data/lib/canon/validators/yaml_validator.rb +3 -1
data/lib/canon/version.rb +1 -1
data/lib/canon/xml/data_model.rb +22 -23
data/lib/canon/xml/element_matcher.rb +128 -20
data/lib/canon/xml/namespace_helper.rb +110 -0
data/lib/canon.rb +3 -0
metadata +81 -23
data/_config.yml +0 -116
data/docs/ADVANCED_TOPICS.adoc +0 -20
data/docs/BASIC_USAGE.adoc +0 -16
data/docs/CUSTOMIZING_BEHAVIOR.adoc +0 -19
data/docs/DIFF_ARCHITECTURE.adoc +0 -435
data/docs/DIFF_FORMATTING.adoc +0 -540
data/docs/FORMATS.adoc +0 -447
data/docs/INPUT_VALIDATION.adoc +0 -477
data/docs/MATCH_ARCHITECTURE.adoc +0 -463
data/docs/MATCH_OPTIONS.adoc +0 -719
data/docs/MODES.adoc +0 -432
data/docs/NORMATIVE_INFORMATIVE_DIFFS.adoc +0 -219
data/docs/OPTIONS.adoc +0 -1387
data/docs/PREPROCESSING.adoc +0 -491
data/docs/SEMANTIC_DIFF_REPORT.adoc +0 -528
data/docs/UNDERSTANDING_CANON.adoc +0 -17

data/docs/features/diff-formatting/context-and-grouping.adoc ADDED Viewed

@@ -0,0 +1,490 @@
+---
+layout: default
+title: Context and Grouping
+parent: Diff Formatting
+grand_parent: Features
+nav_order: 6
+---
+:toc:
+:toclevels: 3
+== Purpose
+Context lines and diff grouping control how much unchanged content is shown around changes in line-by-line diffs. These features help you understand the location and scope of changes while keeping output readable.
+NOTE: Context and grouping apply only to **by-line diff mode**. By-object mode shows only changed elements without context lines.
+== Context Lines
+Context lines are unchanged lines displayed before and after each change to show where modifications occur in the file.
+=== Default Behavior
+By default, Canon shows **3 context lines** before and after each change:
+.Default context example
+[example]
+====
+[source]
+----
+   5|  5 | <section>              # Context line
+   6|  6 |   <title>Intro</title> # Context line
+   7|  7 |   <p>Welcome</p>       # Context line
+   8|   -|   <p>Old text</p>      # Deleted line (change)
+     |  8+|   <p>New text</p>      # Added line (change)
+   9|  9 |   <p>Goodbye</p>       # Context line
+  10| 10 |   <p>End</p>           # Context line
+  11| 11 | </section>             # Context line
+----
+Three unchanged lines are shown before and after the change.
+====
+=== Configuring Context Lines
+Control the number of context lines with the `context_lines` option:
+.CLI
+[example]
+====
+[source,bash]
+----
+# Show 5 context lines
+canon diff file1.xml file2.xml --context-lines 5
+# Show no context (changes only)
+canon diff file1.xml file2.xml --context-lines 0
+# Show 10 context lines
+canon diff file1.xml file2.xml --context-lines 10
+----
+====
+.Ruby API
+[example]
+====
+[source,ruby]
+----
+# Show 5 context lines
+Canon.compare(file1, file2,
+  format: :xml,
+  context_lines: 5
+)
+# Show no context
+Canon.compare(file1, file2,
+  format: :xml,
+  context_lines: 0
+)
+----
+====
+.RSpec
+[example]
+====
+[source,ruby]
+----
+RSpec.configure do |config|
+  # Show more context in local development
+  config.canon.xml.diff.context_lines = 5
+end
+----
+====
+.Environment Variable
+[example]
+====
+[source,bash]
+----
+# Set default context lines globally
+export CANON_CONTEXT_LINES=5
+----
+====
+=== Zero Context Lines
+Setting `context_lines: 0` shows only changed lines without any surrounding context:
+.No context example
+[example]
+====
+[source]
+----
+   8|   -|   <p>Old text</p>      # Only the deletion
+     |  8+|   <p>New text</p>      # Only the addition
+----
+This is useful when:
+* Changes are self-explanatory
+* You want minimal output
+* File structure is already known
+====
+=== Large Context Values
+Larger context values show more surrounding content:
+.Large context example (context_lines: 10)
+[example]
+====
+[source]
+----
+   1|  1 | <root>
+   2|  2 |   <header>
+   3|  3 |     <title>Document</title>
+   4|  4 |   </header>
+   5|  5 |   <body>
+   6|  6 |     <section>
+   7|  7 |       <h1>Title</h1>
+   8|  8 |       <p>Para 1</p>
+   9|  9 |       <p>Para 2</p>
+  10| 10 |       <p>Para 3</p>
+  11|   -|       <p>Old</p>        # The change
+     | 11+|       <p>New</p>
+  12| 12 |       <p>Para 4</p>
+  13| 13 |       <p>Para 5</p>
+  14| 14 |       <p>Para 6</p>
+  15| 15 |     </section>
+  16| 16 |   </body>
+  17| 17 | </root>
+----
+Ten lines of context before and after the change.
+====
+== Diff Grouping
+Diff grouping controls whether nearby changes are shown as separate blocks or merged into a single continuous block.
+=== Default Behavior
+By default, Canon uses **10 lines** as the grouping threshold. Changes within 10 lines of each other are shown in the same context block:
+.Grouped changes (within 10 lines)
+[example]
+====
+[source]
+----
+   5|  5 | <section>
+   6|  6 |   <p>Text 1</p>
+   7|   -|   <p>Old A</p>         # First change
+     |  7+|   <p>New A</p>
+   8|  8 |   <p>Text 2</p>
+   9|  9 |   <p>Text 3</p>
+  10| 10 |   <p>Text 4</p>
+  11| 11 |   <p>Text 5</p>
+  12|   -|   <p>Old B</p>         # Second change (within 10 lines)
+     | 12+|   <p>New B</p>
+  13| 13 |   <p>Text 6</p>
+  14| 14 | </section>
+----
+Both changes appear in one continuous block because they're only 4 lines apart.
+====
+=== Separate Blocks
+When changes are far apart (more than grouping threshold), they appear as separate blocks:
+.Separate blocks (beyond 10 lines apart)
+[example]
+====
+[source]
+----
+   5|  5 | <section>
+   6|  6 |   <p>Text 1</p>
+   7|   -|   <p>Old A</p>         # First change
+     |  7+|   <p>New A</p>
+   8|  8 |   <p>Text 2</p>
+   9|  9 |   <p>Text 3</p>
+  10| 10 | </section>
+  ...  (lines 11-25 omitted)     # Gap indicator
+  26| 26 | <section>
+  27| 27 |   <p>Text N</p>
+  28|   -|   <p>Old B</p>         # Second change (far from first)
+     | 28+|   <p>New B</p>
+  29| 29 |   <p>Text M</p>
+  30| 30 | </section>
+----
+The two changes appear as separate blocks with a gap indicator between them.
+====
+=== Configuring Grouping
+Control grouping behavior with the `diff_grouping_lines` option:
+.CLI
+[example]
+====
+[source,bash]
+----
+# Group changes within 5 lines
+canon diff file1.xml file2.xml --diff-grouping-lines 5
+# Group changes within 20 lines
+canon diff file1.xml file2.xml --diff-grouping-lines 20
+# Never group (each change in its own block)
+canon diff file1.xml file2.xml --diff-grouping-lines 0
+----
+====
+.Ruby API
+[example]
+====
+[source,ruby]
+----
+# Tight grouping (5 lines)
+Canon.compare(file1, file2,
+  format: :xml,
+  diff_grouping_lines: 5
+)
+# Loose grouping (20 lines)
+Canon.compare(file1, file2,
+  format: :xml,
+  diff_grouping_lines: 20
+)
+----
+====
+.RSpec
+[example]
+====
+[source,ruby]
+----
+RSpec.configure do |config|
+  # Tighter grouping for specs
+  config.canon.xml.diff.grouping_lines = 5
+end
+----
+====
+.Environment Variable
+[example]
+====
+[source,bash]
+----
+# Set default grouping globally
+export CANON_GROUPING_LINES=15
+----
+====
+== Interaction Between Context and Grouping
+Context lines and grouping work together to determine diff block boundaries:
+=== Example: Tight Context, Loose Grouping
+.context_lines: 1, diff_grouping_lines: 20
+[example]
+====
+[source]
+----
+   6|  6 |   <p>Text 1</p>       # 1 line context before
+   7|   -|   <p>Old A</p>
+     |  7+|   <p>New A</p>
+   8|  8 |   <p>Text 2</p>       # 1 line context after
+   9|  9 |   <p>Text 3</p>       # Continues because next change within 20 lines
+  10| 10 |   <p>Text 4</p>
+  11| 11 |   <p>Text 5</p>
+  12|   -|   <p>Old B</p>
+     | 12+|   <p>New B</p>
+  13| 13 |   <p>Text 6</p>       # 1 line context after
+----
+Minimal context but changes stay grouped.
+====
+=== Example: Wide Context, Tight Grouping
+.context_lines: 5, diff_grouping_lines: 3
+[example]
+====
+[source]
+----
+# First change block
+   2|  2 | <root>
+   3|  3 |   <section>
+   4|  4 |     <p>A</p>
+   5|  5 |     <p>B</p>
+   6|  6 |     <p>C</p>
+   7|   -|     <p>Old A</p>
+     |  7+|     <p>New A</p>
+   8|  8 |     <p>D</p>
+   9|  9 |     <p>E</p>
+  10| 10 |     <p>F</p>
+  11| 11 |     <p>G</p>
+  12| 12 |     <p>H</p>
+  ...  (lines 13-17 omitted)
+# Second change block (separated by > 3 lines)
+  13| 13 |     <p>I</p>
+  14| 14 |     <p>J</p>
+  15| 15 |     <p>K</p>
+  16| 16 |     <p>L</p>
+  17| 17 |     <p>M</p>
+  18|   -|     <p>Old B</p>
+     | 18+|     <p>New B</p>
+  19| 19 |     <p>N</p>
+  20| 20 |     <p>O</p>
+  21| 21 |     <p>P</p>
+  22| 22 |     <p>Q</p>
+  23| 23 |   </section>
+----
+Wide context but changes in separate blocks due to tight grouping.
+====
+== Use Cases
+=== Debugging: Wide Context
+When debugging unexpected test failures, use wide context to see surrounding structure:
+[source,bash]
+----
+canon diff expected.xml actual.xml \
+  --context-lines 10 \
+  --diff-grouping-lines 20
+----
+=== CI/CD: Minimal Output
+In CI environments, minimize output for faster log scanning:
+[source,bash]
+----
+export CANON_CONTEXT_LINES=1
+export CANON_GROUPING_LINES=5
+----
+=== Documentation: Complete Context
+When documenting changes, show complete sections:
+[source,ruby]
+----
+Canon.compare(old_doc, new_doc,
+  format: :xml,
+  context_lines: 15,
+  diff_grouping_lines: 30
+)
+----
+=== Code Review: Balanced View
+For code reviews, balance readability and completeness:
+[source,ruby]
+----
+RSpec.configure do |config|
+  config.canon.xml.diff.context_lines = 5
+  config.canon.xml.diff.grouping_lines = 10
+end
+----
+== Performance Considerations
+=== Large Files
+With large files and many changes:
+* **Smaller context**: Reduces output size, faster to scan
+* **Tighter grouping**: More separate blocks, easier to locate specific changes
+* **Larger context**: Better understanding, but more verbose
+.Recommended for large files
+[example]
+====
+[source,bash]
+----
+# Keep output manageable
+canon diff large1.xml large2.xml \
+  --context-lines 2 \
+  --diff-grouping-lines 5
+----
+====
+=== Many Small Changes
+When files have numerous small scattered changes:
+* **Smaller context**: Avoids repetitive output
+* **Tighter grouping**: Keeps unrelated changes separate
+* **Larger grouping**: May merge everything into one block
+.Recommended for scattered changes
+[example]
+====
+[source,bash]
+----
+# Separate unrelated changes
+canon diff file1.xml file2.xml \
+  --context-lines 1 \
+  --diff-grouping-lines 3
+----
+====
+== Gap Indicators
+When changes are far apart, Canon shows gap indicators:
+[source]
+----
+  10| 10 |   <p>End of first section</p>
+  ...  (lines 11-45 omitted)
+  46| 46 |   <p>Start of next section</p>
+----
+The gap indicator shows:
+* How many lines were skipped
+* That there are no changes in the skipped region
+== Troubleshooting
+=== Too Much Output
+**Problem**: Diff output is overwhelming.
+**Solutions**:
+* Reduce `context_lines` (try 1 or 2)
+* Reduce `diff_grouping_lines` (try 5 or less)
+* Use `show_diffs: :normative` to hide informative changes
+=== Not Enough Context
+**Problem**: Can't understand where changes occur.
+**Solutions**:
+* Increase `context_lines` (try 7-10)
+* Increase `diff_grouping_lines` (try 15-20)
+* Check file structure separately
+=== Changes Grouped Incorrectly
+**Problem**: Unrelated changes appear together.
+**Solution**:
+* Decrease `diff_grouping_lines` to separate them
+**Problem**: Related changes appear in separate blocks.
+**Solution**:
+* Increase `diff_grouping_lines` to group them together
+== See Also
+* link:colors-and-symbols.html[Colors and Symbols] - Color scheme and visual markers
+* link:character-visualization.html[Character Visualization] - Whitespace visualization
+* link:algorithm-specific-output.html[Algorithm-Specific Output] - Diff format variations
+* link:../../interfaces/cli/index.html[CLI Interface] - Command-line usage
+* link:../../reference/cli-options.html[CLI Options Reference] - Complete option list