canon 0.1.6 → 0.1.7

data/docs/features/environment-configuration/override-system.adoc

@@ -0,0 +1,436 @@
+---
+title: Override System
+parent: Environment Configuration
+grand_parent: Features
+nav_order: 2
+---
+= Override system
+:toc:
+:toclevels: 3
+
+== Purpose
+
+Canon's override system allows environment variables to take precedence over programmatic configuration, enabling flexible deployment without code changes.
+
+This page explains how the priority chain works, when overrides apply, and how to use them effectively.
+
+== Priority chain
+
+Configuration values are resolved using a strict three-level priority:
+
+[source]
+----
+┌─────────────────────────────────┐
+│ 1. Environment Variables        │ ← Highest Priority
+│    (CANON_XML_DIFF_ALGORITHM)   │
+└──────────────┬──────────────────┘
+               ↓ overrides
+┌─────────────────────────────────┐
+│ 2. Programmatic Configuration   │ ← Medium Priority
+│    (config.xml.diff.algorithm)  │
+└──────────────┬──────────────────┘
+               ↓ overrides
+┌─────────────────────────────────┐
+│ 3. Default Values               │ ← Lowest Priority
+│    (defined in Canon::Config)   │
+└─────────────────────────────────┘
+----
+
+**Rule**: Higher priority always wins, regardless of when values are set.
+
+== How overrides work
+
+=== Environment variables override programmatic settings
+
+When an environment variable is set, it **always** takes precedence:
+
+[source,ruby]
+----
+# Set ENV before requiring Canon
+ENV['CANON_XML_DIFF_ALGORITHM'] = 'semantic'
+
+# Programmatic setting is IGNORED
+config = Canon::Config.instance
+config.xml.diff.algorithm = :dom
+
+# ENV wins
+puts config.xml.diff.algorithm  # => :semantic (not :dom)
+----
+
+=== Format-specific variables override global variables
+
+Format-specific ENV vars override global ENV vars:
+
+[source,bash]
+----
+# Global setting
+export CANON_ALGORITHM=dom
+
+# Format-specific override
+export CANON_XML_DIFF_ALGORITHM=semantic
+
+# Result:
+# - XML uses semantic (format-specific wins)
+# - HTML, JSON, YAML use dom (global applies)
+----
+
+=== Setting order doesn't matter
+
+Unlike programmatic configuration, ENV variable priority is **positional**, not temporal:
+
+[source,ruby]
+----
+# Set ENV first
+ENV['CANON_ALGORITHM'] = 'semantic'
+
+# Configure programmatically later
+config = Canon::Config.instance
+config.xml.diff.algorithm = :dom  # This is IGNORED
+
+# ENV still wins, even though set "earlier"
+puts config.xml.diff.algorithm  # => :semantic
+----
+
+== When to use environment variables
+
+=== Use ENV variables for
+
+**CI/CD configuration**::
+Different test runs need different settings without code changes.
++
+[source,bash]
+----
+# In .github/workflows/test.yml
+env:
+  CANON_ALGORITHM: semantic
+  CANON_USE_COLOR: false
+----
+
+**Container deployment**::
+Docker containers with different comparison behavior.
++
+[source,dockerfile]
+----
+# Dockerfile
+ENV CANON_XML_DIFF_ALGORITHM=semantic
+ENV CANON_CONTEXT_LINES=5
+----
+
+**Environment-specific behavior**::
+Different settings for development, staging, production.
++
+[source,bash]
+----
+# Development
+export CANON_VERBOSE_DIFF=true
+
+# Production
+export CANON_VERBOSE_DIFF=false
+----
+
+**Testing algorithm behavior**::
+Quick switching between algorithms for comparison.
++
+[source,bash]
+----
+# Test with DOM
+CANON_ALGORITHM=dom bundle exec rspec
+
+# Test with semantic
+CANON_ALGORITHM=semantic bundle exec rspec
+----
+
+=== Use programmatic config for
+
+**Application defaults**::
+Set sensible defaults in your application code.
++
+[source,ruby]
+----
+# config/initializers/canon.rb
+Canon::Config.configure do |config|
+  config.xml.diff.algorithm = :dom
+  config.xml.diff.use_color = true
+end
+----
+
+**Test-specific overrides**::
+Per-test configuration in RSpec.
++
+[source,ruby]
+----
+RSpec.describe "My feature" do
+  it "compares with specific options" do
+    result = Canon::Comparison.equivalent?(doc1, doc2,
+      diff_algorithm: :semantic  # Test-specific
+    )
+  end
+end
+----
+
+**Dynamic configuration**::
+Runtime decisions based on document size or other factors.
++
+[source,ruby]
+----
+algorithm = file_size > 100_000 ? :dom : :semantic
+Canon::Comparison.equivalent?(doc1, doc2,
+  diff_algorithm: algorithm
+)
+----
+
+== Verification and debugging
+
+=== Check which source provides a value
+
+Use the resolver to inspect configuration sources:
+
+[source,ruby]
+----
+config = Canon::Config.instance
+resolver = config.xml.diff.instance_variable_get(:@resolver)
+
+# Check sources
+puts "Algorithm from: #{resolver.source_for(:algorithm)}"
+# => "env" | "programmatic" | "default"
+
+# See all sources
+puts "ENV values: #{resolver.env.inspect}"
+puts "Programmatic values: #{resolver.programmatic.inspect}"
+puts "Defaults: #{resolver.defaults.inspect}"
+----
+
+=== List all active ENV variables
+
+[source,ruby]
+----
+# Get all Canon ENV variables
+canon_env = ENV.select { |k, v| k.start_with?('CANON_') }
+puts "Active Canon ENV variables:"
+canon_env.each do |key, value|
+  puts "  #{key} = #{value}"
+end
+----
+
+=== Test ENV override behavior
+
+[source,ruby]
+----
+# Verify ENV takes precedence
+ENV['CANON_ALGORITHM'] = 'semantic'
+
+config = Canon::Config.instance
+config.xml.diff.algorithm = :dom  # Should be ignored
+
+if config.xml.diff.algorithm == :semantic
+  puts "✓ ENV override working correctly"
+else
+  puts "✗ ENV override NOT working!"
+end
+----
+
+== Common patterns
+
+=== Pattern 1: Sensible defaults with ENV override
+
+[source,ruby]
+----
+# config/initializers/canon.rb
+# Set defaults that work for most cases
+Canon::RSpecMatchers.configure do |config|
+  config.xml.diff.algorithm = :dom
+  config.xml.diff.use_color = !ENV['CI']
+end
+
+# Users can override per test run:
+# CANON_ALGORITHM=semantic bundle exec rspec
+----
+
+=== Pattern 2: Environment-based configuration
+
+[source,ruby]
+----
+# config/environments/development.rb
+ENV['CANON_VERBOSE_DIFF'] = 'true'
+ENV['CANON_USE_COLOR'] = 'true'
+
+# config/environments/production.rb
+ENV['CANON_VERBOSE_DIFF'] = 'false'
+ENV['CANON_USE_COLOR'] = 'false'
+----
+
+=== Pattern 3: CI matrix testing
+
+[source,yaml]
+----
+# .github/workflows/test.yml
+strategy:
+  matrix:
+    algorithm: [dom, semantic]
+steps:
+  - name: Run tests
+    env:
+      CANON_ALGORITHM: ${{ matrix.algorithm }}
+    run: bundle exec rspec
+----
+
+=== Pattern 4: Format-specific CI configuration
+
+[source,yaml]
+----
+# .github/workflows/test.yml
+env:
+  CANON_XML_DIFF_ALGORITHM: semantic  # XML uses semantic
+  CANON_HTML_DIFF_ALGORITHM: dom      # HTML uses DOM
+  CANON_USE_COLOR: false              # All formats: no color
+----
+
+== Troubleshooting
+
+=== ENV variable not working
+
+**Problem**: ENV variable seems to be ignored.
+
+**Checklist**:
+
+1. **Variable name correct?**
++
+[source,bash]
+----
+# Correct
+export CANON_XML_DIFF_ALGORITHM=semantic
+
+# Wrong (underscore placement)
+export CANON_XML_DIFFALGORITHM=semantic
+----
+
+2. **ENV set before Canon loads?**
++
+[source,ruby]
+----
+# Wrong order
+require 'canon'
+ENV['CANON_ALGORITHM'] = 'semantic'  # Too late!
+
+# Correct order
+ENV['CANON_ALGORITHM'] = 'semantic'
+require 'canon'
+----
+
+3. **Value valid for attribute type?**
++
+[source,bash]
+----
+# Wrong (should be symbol name)
+export CANON_ALGORITHM=:semantic
+
+# Correct
+export CANON_ALGORITHM=semantic
+----
+
+=== Programmatic setting not working
+
+**Problem**: Setting `config.xml.diff.algorithm = :semantic` doesn't work.
+
+**Solution**: Check if ENV variable is set:
+
+[source,bash]
+----
+# Check current ENV
+echo $CANON_XML_DIFF_ALGORITHM
+echo $CANON_ALGORITHM
+
+# If set, unset it
+unset CANON_XML_DIFF_ALGORITHM
+unset CANON_ALGORITHM
+----
+
+=== Inconsistent behavior across runs
+
+**Problem**: Tests behave differently on different machines.
+
+**Cause**: One machine has Canon ENV variables set in shell profile.
+
+**Solution**: Document required ENV variables or unset them in test setup:
+
+[source,ruby]
+----
+# spec/spec_helper.rb
+RSpec.configure do |config|
+  config.before(:suite) do
+    # Clear any Canon ENV vars to ensure consistent tests
+    ENV.keys.select { |k| k.start_with?('CANON_') }.each do |key|
+      ENV.delete(key)
+    end
+  end
+end
+----
+
+== Best practices
+
+=== Document expected ENV variables
+
+Create a `.env.example` or document ENV variables:
+
+[source,bash]
+----
+# .env.example
+# Canon Configuration
+# Uncomment and modify as needed
+
+# CANON_ALGORITHM=dom
+# CANON_USE_COLOR=true
+# CANON_MAX_FILE_SIZE=5242880
+----
+
+=== Use ENV for deployment, code for defaults
+
+[source,ruby]
+----
+# Good: Code provides defaults
+Canon::RSpecMatchers.configure do |config|
+  config.xml.diff.algorithm = :dom  # Default
+end
+
+# Good: ENV overrides for deployment
+# In production: CANON_ALGORITHM=semantic
+----
+
+=== Avoid mixing ENV and programmatic for same attribute
+
+[source,ruby]
+----
+# Confusing: Don't do this
+ENV['CANON_ALGORITHM'] = 'semantic'
+config.xml.diff.algorithm = :dom  # Ignored, but confusing
+
+# Better: Use one or the other consistently
+ENV['CANON_ALGORITHM'] = 'semantic'
+# OR
+config.xml.diff.algorithm = :dom
+----
+
+=== Test with both ENV and without
+
+[source,ruby]
+----
+RSpec.describe "Canon behavior" do
+  context "without ENV override" do
+    before { ENV.delete('CANON_ALGORITHM') }
+    # Tests...
+  end
+
+  context "with ENV override" do
+    before { ENV['CANON_ALGORITHM'] = 'semantic' }
+    after { ENV.delete('CANON_ALGORITHM') }
+    # Tests...
+  end
+end
+----
+
+== See also
+
+* link:index.adoc[Environment Configuration] - Overview and usage
+* link:size-limits.adoc[Size Limits] - Limit-specific ENV variables
+* link:../../reference/environment-variables.adoc[Environment Variables Reference] - Complete listing
+* link:../../reference/options-across-interfaces.adoc[Options Across Interfaces] - How options work in CLI, Ruby, RSpec

data/docs/features/environment-configuration/size-limits.adoc

@@ -0,0 +1,273 @@
+---
+title: Size Limits
+parent: Environment Configuration
+grand_parent: Features
+nav_order: 1
+---
+= Size limits
+:toc:
+:toclevels: 3
+
+== Purpose
+
+Canon provides configurable size limits to prevent hangs or excessive resource usage when processing very large files. These limits apply uniformly across all interfaces (CLI, Ruby API, RSpec).
+
+== Available limits
+
+=== File size limit
+
+Maximum file size in bytes before comparison is rejected.
+
+**Environment variable**: `CANON_MAX_FILE_SIZE` or `CANON_{FORMAT}_DIFF_MAX_FILE_SIZE`
+
+**Default**: 5,242,880 bytes (5 MB)
+
+**When triggered**: Before parsing, if either input file exceeds this size
+
+[source,bash]
+----
+# Set max file size to 10MB for XML
+export CANON_XML_DIFF_MAX_FILE_SIZE=10485760
+
+# Set globally (5MB default)
+export CANON_MAX_FILE_SIZE=5242880
+----
+
+=== Node count limit
+
+Maximum number of nodes in a tree structure before comparison is rejected.
+
+**Environment variable**: `CANON_MAX_NODE_COUNT` or `CANON_{FORMAT}_DIFF_MAX_NODE_COUNT`
+
+**Default**: 10,000 nodes
+
+**When triggered**: After parsing, if the document tree exceeds this node count
+
+[source,bash]
+----
+# Set max node count for XML diff
+export CANON_XML_DIFF_MAX_NODE_COUNT=20000
+
+# Set globally (10,000 default)
+export CANON_MAX_NODE_COUNT=10000
+----
+
+=== Diff output lines limit
+
+Maximum number of lines in diff output before truncation.
+
+**Environment variable**: `CANON_MAX_DIFF_LINES` or `CANON_{FORMAT}_DIFF_MAX_DIFF_LINES`
+
+**Default**: 10,000 lines
+
+**When triggered**: During diff generation, output is truncated at this line count
+
+[source,bash]
+----
+# Set max diff lines for XML
+export CANON_XML_DIFF_MAX_DIFF_LINES=15000
+
+# Set globally (10,000 default)
+export CANON_MAX_DIFF_LINES=10000
+----
+
+== Common scenarios
+
+=== Large SVG files
+
+When working with large SVG files (e.g., 3.5MB) that may cause hangs:
+
+[source,bash]
+----
+# Increase limits for large SVG processing
+export CANON_MAX_FILE_SIZE=10485760      # 10MB
+export CANON_MAX_NODE_COUNT=50000        # 50,000 nodes
+export CANON_MAX_DIFF_LINES=20000        # 20,000 lines
+
+bundle exec rspec spec/test_031_spec.rb
+----
+
+=== CI/CD with large documents
+
+In CI environments where you know documents are large but safe:
+
+[source,bash]
+----
+# In .github/workflows/test.yml
+env:
+  CANON_MAX_FILE_SIZE: 20971520    # 20MB
+  CANON_MAX_NODE_COUNT: 100000     # 100k nodes
+  CANON_MAX_DIFF_LINES: 50000      # 50k lines
+----
+
+=== Format-specific limits
+
+Different formats may need different limits:
+
+[source,bash]
+----
+# XML can have more nodes
+export CANON_XML_DIFF_MAX_NODE_COUNT=50000
+
+# JSON typically has fewer nodes
+export CANON_JSON_DIFF_MAX_NODE_COUNT=10000
+
+# HTML might need larger file size
+export CANON_HTML_DIFF_MAX_FILE_SIZE=10485760
+----
+
+== Disabling limits
+
+To disable a limit, set it to 0 or a negative value:
+
+[source,bash]
+----
+# Disable file size limit (not recommended)
+export CANON_MAX_FILE_SIZE=0
+
+# Disable node count limit (use with caution)
+export CANON_MAX_NODE_COUNT=-1
+----
+
+WARNING: Disabling limits may cause Canon to hang or consume excessive memory on pathologically large inputs.
+
+== Error messages
+
+When a limit is exceeded, Canon raises a clear error:
+
+=== File size exceeded
+
+[source]
+----
+Canon::ValidationError: File size exceeds maximum limit
+  Maximum: 5242880 bytes (5.0 MB)
+  Actual: 10485760 bytes (10.0 MB)
+
+  To increase this limit, set:
+    CANON_MAX_FILE_SIZE=10485760
+----
+
+=== Node count exceeded
+
+[source]
+----
+Canon::ValidationError: Node count exceeds maximum limit
+  Maximum: 10000 nodes
+  Actual: 25000 nodes
+
+  To increase this limit, set:
+    CANON_MAX_NODE_COUNT=25000
+----
+
+=== Diff lines exceeded
+
+[source]
+----
+Canon::DiffTruncationWarning: Diff output truncated
+  Maximum: 10000 lines
+  Actual: 15000 lines (truncated to 10000)
+
+  To increase this limit, set:
+    CANON_MAX_DIFF_LINES=15000
+----
+
+== Programmatic configuration
+
+While environment variables are recommended, you can also configure limits programmatically:
+
+[source,ruby]
+----
+# NOT RECOMMENDED - use ENV vars instead
+Canon::Config.instance.xml.diff.max_file_size = 10_485_760
+Canon::Config.instance.xml.diff.max_node_count = 50_000
+Canon::Config.instance.xml.diff.max_diff_lines = 20_000
+----
+
+However, **environment variables will override programmatic settings** per the priority chain.
+
+== Performance considerations
+
+=== Why limits exist
+
+Limits prevent:
+
+* **Hangs**: Very large documents can cause O(n²) algorithms to hang
+* **Memory exhaustion**: Huge trees consume excessive RAM
+* **Unreadable output**: 100k+ line diffs are not useful
+
+=== Choosing appropriate limits
+
+**File size**:
+
+* **Small projects**: 5MB default is fine
+* **Large documents**: 10-20MB for SVG, generated HTML
+* **Very large**: 50MB+ only if you know what you're doing
+
+**Node count**:
+
+* **Simple documents**: 10k default is fine
+* **Complex documents**: 50k for large XML, nested JSON
+* **Very complex**: 100k+ only for known-safe inputs
+
+**Diff lines**:
+
+* **Readable output**: 10k default is fine
+* **Detailed diffs**: 20-50k for comprehensive output
+* **Debug mode**: 100k+ for full comparison
+
+== Troubleshooting
+
+=== Tests failing with size limit errors
+
+If your tests start failing due to size limits:
+
+1. **Verify the limit is appropriate**: Check if documents really are that large
+2. **Set ENV in test helper**:
++
+[source,ruby]
+----
+# spec/spec_helper.rb
+ENV['CANON_MAX_FILE_SIZE'] = '10485760'  # 10MB
+ENV['CANON_MAX_NODE_COUNT'] = '50000'
+----
+
+3. **Or set per-test**:
++
+[source,ruby]
+----
+around do |example|
+  ClimateControl.modify(
+    CANON_MAX_FILE_SIZE: '10485760'
+  ) do
+    example.run
+  end
+end
+----
+
+=== Performance degradation
+
+If comparisons become slow after increasing limits:
+
+1. **Use DOM algorithm**: Faster than semantic for large documents
++
+[source,bash]
+----
+export CANON_ALGORITHM=dom
+----
+
+2. **Disable expensive features**:
++
+[source,bash]
+----
+export CANON_SHOW_COMPARE=false
+export CANON_VERBOSE_DIFF=false
+----
+
+3. **Consider if you really need to compare such large files**
+
+== See also
+
+* link:index.adoc[Environment Configuration] - Complete ENV configuration
+* link:override-system.adoc[Override System] - How ENV vars work
+* link:../../reference/environment-variables.adoc[Environment Variables Reference] - All variables
+* link:../../understanding/algorithms/dom-diff.adoc[DOM Algorithm] - Faster for large files