svg_conform 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4879f5648a06585ca68ae1430f928c327b267c3de96e92ae54333a002127243
-  data.tar.gz: 7fb876639e3d0d935020089981803d43e2648131bf7a074b0b127605c99009ff
+  metadata.gz: 9300ab0026e52b929e0707e14c19ce45394da831dfd5e44f4afad14e1a2237cd
+  data.tar.gz: b19b0d2dbce1397abb478105704c994a32f418972240c9c149d375d8be519e2c
 SHA512:
-  metadata.gz: ca32f36fb1bcb98fc25be20fc237291f5fa0efedd55c71cb62b8862e60c3628f05673a0d16def9deda237e4a3b53312c78e39d3daf2bb42700e58f388a2d38c8
-  data.tar.gz: '0086cffd30f8c81aba4e157caf6a0bfe197f4ce597971941e4ddcc136f0ac7cf11460eb8e4103094a6636aa546c5d687c0f724697e441c509a94e1697bc41857'
+  metadata.gz: d413baac7ebb781837ff482103d751ce3222c170c613707b8411d5c6614dff71ac874802e0e5df14e276c0d56f537d32259787559359dfb954f6e3392088102d
+  data.tar.gz: ca1a62500f77534fca87d5b0e0136328ed81b9d9a7a81510e312a3760f31157e7a42af4934bacda3af2d6915b675bb9f4afdba2746332922cb23351bcc47fba2

data/.gitignore

@@ -10,3 +10,7 @@
 # rspec failure tracking
 .rspec_status
 svgcheck-reference/
+
+.kilocode
+.claude
+

data/.rubocop_todo.yml

@@ -1,11 +1,19 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-01-22 08:33:31 UTC using RuboCop version 1.82.1.
+# on 2026-01-27 00:27:35 UTC using RuboCop version 1.82.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/svg_conform/requirements/invalid_id_references_requirement.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleAlignWith.
@@ -14,7 +22,17 @@ Layout/BlockAlignment:
   Exclude:
     - 'spec/svg_conform/profiles/svg_1_2_rfc_profile_spec.rb'
 
-# Offense count: 647
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'spec/svg_conform/validation_context_spec.rb'
+
+# Offense count: 662
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -22,6 +40,14 @@ Layout/LineLength:
   Enabled: false
 
 # Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/svg_conform/requirements/invalid_id_references_requirement.rb'
+    - 'spec/svg_conform/validation_context_spec.rb'
+
+# Offense count: 3
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
 Lint/ConstantDefinitionInBlock:
@@ -70,7 +96,7 @@ Lint/UnreachableCode:
   Exclude:
     - 'lib/svg_conform/commands/check.rb'
 
-# Offense count: 151
+# Offense count: 146
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -81,17 +107,17 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 253
 
-# Offense count: 6
+# Offense count: 2
 # Configuration parameters: CountBlocks, CountModifierForms.
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 127
+# Offense count: 125
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 263
+# Offense count: 259
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 154
@@ -101,18 +127,11 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 101
+# Offense count: 99
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
 
-# Offense count: 4
-# Configuration parameters: EnforcedStyle, AllowedIdentifiers, AllowedPatterns, ForbiddenIdentifiers, ForbiddenPatterns.
-# SupportedStyles: snake_case, camelCase
-Naming/VariableName:
-  Exclude:
-    - 'check_clippath_font.rb'
-
 # Offense count: 2
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:
@@ -139,12 +158,12 @@ RSpec/DescribeClass:
     - 'spec/svg_conform/references/integration_spec.rb'
     - 'spec/svgcheck_compatibility_spec.rb'
 
-# Offense count: 139
+# Offense count: 157
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 53
 
-# Offense count: 2
+# Offense count: 3
 RSpec/LeakyConstantDeclaration:
   Exclude:
     - 'spec/svg_conform/profiles/svg_1_2_rfc_profile_spec.rb'
@@ -160,7 +179,7 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/svg_conform/batch_report_spec.rb'
 
-# Offense count: 111
+# Offense count: 126
 RSpec/MultipleExpectations:
   Max: 8
 

data/benchmark/performance_comparison.rb

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Performance benchmark for svg_conform optimizations
+# Measures validation speed for single and batch operations
+
+require "bundler/setup"
+require "benchmark"
+require_relative "../lib/svg_conform"
+
+# Helper method to create test SVG content
+def create_test_svg(element_count: 10, attribute_count: 5)
+  elements = (1..element_count).map do |i|
+    attrs = (1..attribute_count).map { |j| "attr#{j}='value#{j}'" }.join(" ")
+    "<rect id='rect#{i}' x='#{i * 10}' y='#{i * 10}' width='10' height='10' #{attrs}/>"
+  end
+
+  <<~SVG
+    <?xml version="1.0"?>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 1000">
+      #{elements.join("\n      ")}
+    </svg>
+  SVG
+end
+
+puts "=" * 80
+puts "svg_conform Performance Benchmark"
+puts "=" * 80
+puts
+
+# Test configurations
+test_cases = [
+  { name: "Small document", elements: 10, attributes: 3 },
+  { name: "Medium document", elements: 50, attributes: 5 },
+  { name: "Large document", elements: 100, attributes: 8 },
+]
+
+validator = SvgConform::Validator.new
+
+test_cases.each do |test_case|
+  puts "Test: #{test_case[:name]}"
+  puts "  Elements: #{test_case[:elements]}, Attributes per element: #{test_case[:attributes]}"
+  puts
+
+  svg_content = create_test_svg(element_count: test_case[:elements],
+                                attribute_count: test_case[:attributes])
+
+  # Warmup run
+  validator.validate(svg_content, profile: :svg_1_2_rfc)
+
+  # Benchmark single validation
+  single_time = Benchmark.measure do
+    100.times do
+      validator.validate(svg_content, profile: :svg_1_2_rfc)
+    end
+  end
+
+  puts "  Single validation (100 runs): #{(single_time.real * 1000).round(2)}ms"
+  puts "    Average per validation: #{(single_time.real * 10).round(2)}ms"
+
+  # Benchmark batch validation
+  contents = Array.new(10) do
+    create_test_svg(element_count: test_case[:elements],
+                    attribute_count: test_case[:attributes])
+  end
+
+  batch_time = Benchmark.measure do
+    10.times do
+      contents.each do |content|
+        validator.validate(content, profile: :svg_1_2_rfc)
+      end
+    end
+  end
+
+  puts "  Batch validation (10 files × 10 runs): #{(batch_time.real * 1000).round(2)}ms"
+  puts "    Average per file: #{(batch_time.real * 100).round(2)}ms"
+  puts
+end
+
+puts "=" * 80
+puts "Memory Profiling"
+puts "=" * 80
+puts
+
+if Object.const_defined?(:GC)
+  GC.start
+  before_mem = `ps -o rss= -p #{Process.pid}`.to_i
+
+  # Create and validate 100 documents
+  100.times do
+    svg = create_test_svg(element_count: 50, attribute_count: 5)
+    validator.validate(svg, profile: :svg_1_2_rfc)
+  end
+
+  GC.start
+  after_mem = `ps -o rss= -p #{Process.pid}`.to_i
+
+  mem_increase = after_mem - before_mem
+  puts "  RSS memory increase: #{mem_increase} KB"
+  puts "  Per validation: #{(mem_increase / 100.0).round(2)} KB"
+else
+  puts "  Memory profiling not available on this platform"
+end
+
+puts
+puts "=" * 80
+puts "Benchmark Complete"
+puts "=" * 80
+puts
+puts "Optimizations tested:"
+puts "  ✓ Phase 1.1: ElementProxy#path_id memoization"
+puts "  ✓ Phase 1.2: Element configuration index"
+puts "  ✓ Phase 2.1: Requirement classification cache"
+puts "  ✓ Phase 2.2: Global properties constant"
+puts "  ✓ Phase 2.3: ElementProxy attributes cache"
+puts "  ✓ Phase 3.1: Configuration validation cache"
+puts "  ✓ Phase 3.3: ProfileCompiler class"
+puts "  ✓ Phase 4.1: TrackerFactory extraction"
+puts "  ✓ Phase 5.1: Batch validation optimization"
+puts

data/docs/performance.adoc

@@ -0,0 +1,239 @@
+= Performance Optimization Guide
+
+This guide documents the performance optimization patterns used in svg_conform.
+
+== Goals
+
+The performance optimization strategy focuses on:
+
+* Reducing validation time for repeated operations
+* Minimizing memory allocations during SAX parsing
+* Caching expensive operations without introducing complexity
+* Maintaining clean separation of concerns
+
+== Optimization Patterns
+
+=== Memoization
+
+Cache computed values to avoid repeated calculations.
+
+*Example:* `ElementProxy#path_id` uses `@cached_path_id` to store the computed path:
+
+[source,ruby]
+----
+def path_id
+  @cached_path_id ||= begin
+    parts = @path + ["#{@name}[#{@position]}"]
+    "/#{parts.join('/')}"
+  end
+end
+----
+
+*When to use:* When a method is called multiple times with the same result and the computation is expensive.
+
+*When to avoid:* When the result changes between calls, or the computation is trivial.
+
+=== Class-Level Caching with Thread Safety
+
+Use class-level caches with Mutex for thread-safe shared state.
+
+*Example:* Requirement classification cache in `SaxValidationHandler`:
+
+[source,ruby]
+----
+@classification_cache = {}
+@classification_cache_mutex = Mutex.new
+
+def classify_requirements_with_cache
+  profile_key = @profile.class.name
+  classified = self.class.classification_cache_mutex.synchronize do
+    self.class.classification_cache[profile_key]
+  end
+
+  # ... compute and cache if not found
+end
+----
+
+*When to use:* When the cached value is shared across all instances and doesn't change.
+
+*When to avoid:* When the cached value is instance-specific or changes frequently.
+
+=== Frozen Constants
+
+Define immutable data as frozen constants to avoid reallocations.
+
+*Example:* `GLOBAL_PROPERTIES` constant in `AllowedElementsRequirement`:
+
+[source,ruby]
+----
+GLOBAL_PROPERTIES = %w[
+  about base baseprofile d break class content cx cy
+  # ... full list of properties
+].freeze
+----
+
+*When to use:* For lookup tables, configuration data, and other immutable collections.
+
+*When to avoid:* When the data needs to be modified at runtime.
+
+=== Hash Indexes for O(1) Lookups
+
+Pre-build hash indexes for fast lookups instead of linear array searches.
+
+*Example:* Element configuration index in `AllowedElementsRequirement`:
+
+[source,ruby]
+----
+def after_initialize
+  build_element_config_index if element_configs&.any?
+end
+
+def build_element_config_index
+  @element_config_index = {}
+  element_configs.each do |config|
+    @element_config_index[config.tag] = config
+  end
+end
+
+# Usage - O(1) instead of O(n)
+element_config = @element_config_index&.dig(element_name)
+----
+
+*When to use:* When frequently looking up items by key in a collection.
+
+*When to avoid:* When the collection is small or accessed sequentially.
+
+=== Lazy Initialization with `||=`
+
+Use the "or-equals" operator for lazy initialization.
+
+*Example:* Cached attributes array in `ElementProxy`:
+
+[source,ruby]
+----
+def attributes
+  @cached_attributes ||= @raw_attributes.map { |name, value| SaxAttribute.new(name, value) }
+end
+----
+
+*When to use:* When a value is expensive to compute and may not be needed.
+
+*When to avoid:* When `nil` or `false` are valid cached values (use explicit nil check instead).
+
+=== Batch Processing Optimization
+
+Amortize fixed costs across multiple operations.
+
+*Example:* Batch file validation in `Validator`:
+
+[source,ruby]
+----
+def validate_files(file_paths, profile: :svg_1_2_rfc, **options)
+  # Load profile once
+  profile_obj = resolve_profile(profile)
+
+  file_paths.each do |file_path|
+    validate_file_with_profile(file_path, profile_obj, **options)
+  end
+end
+----
+
+*When to use:* When processing multiple items with shared setup costs.
+
+*When to avoid:* When processing single items or when items have different configurations.
+
+=== Factory Pattern for Complex Initialization
+
+Centralize object creation for cleaner initialization.
+
+*Example:* `TrackerFactory` for creating validation trackers:
+
+[source,ruby]
+----
+module Validation
+  module TrackerFactory
+    def self.create_all_trackers(document)
+      node_id_manager = create_node_id_manager(document)
+
+      {
+        error_tracker: create_error_tracker,
+        node_id_manager: node_id_manager,
+        # ... other trackers
+      }
+    end
+  end
+end
+----
+
+*When to use:* When initialization involves multiple related objects or complex logic.
+
+*When to avoid:* For simple object creation that doesn't benefit from centralization.
+
+== Anti-Patterns to Avoid
+
+=== Premature Optimization
+
+Don't optimize without benchmarks. Measure first, then optimize.
+
+=== Global Mutable State
+
+Avoid mutable global state. Use class-level caches with thread-safe access.
+
+=== Over-Abstraction
+
+Don't create abstractions just for the sake of it. Each abstraction should pull its weight.
+
+=== Optimizing Uncommon Paths
+
+Focus on hot paths. Don't optimize code that rarely runs.
+
+=== Sacrificing Readability
+
+Performance gains should not come at the cost of code clarity.
+
+== Performance Metrics
+
+The `benchmark/performance_comparison.rb` script measures:
+
+* Single validation speed (average time per document)
+* Batch validation speed (average time per file)
+* Memory usage per validation
+
+Run benchmarks before and after optimizations to measure impact:
+
+[source,shell]
+----
+ruby benchmark/performance_comparison.rb
+----
+
+== Architecture Considerations
+
+=== SAX vs DOM Validation
+
+svg_conform uses SAX validation by default for better performance:
+
+* *SAX mode*: Constant memory, streaming parser, handles large files
+* *DOM mode*: Loads full document, uses more memory, slower for large files
+
+Always prefer SAX for validation. Only use DOM when applying remediations.
+
+=== Caching Strategy
+
+* *Instance-level cache*: Use for data specific to a validation run
+* *Class-level cache*: Use for data shared across all instances
+* *Thread safety*: Always use Mutex for class-level shared state
+
+== Future Optimization Opportunities
+
+Areas that may benefit from future optimization:
+
+* Parallel batch validation for multi-core systems
+* Compiled profiles with pre-computed lookup tables
+* Streaming remediation to avoid full DOM load
+* Attribute name interning for reduced memory
+
+== Further Reading
+
+* `PERFORMANCE_OPTIMIZATION_PLAN.md` - Detailed optimization plan
+* `CLAUDE.md` - Architecture overview
+* `benchmark/performance_comparison.rb` - Performance benchmarks

data/lib/svg_conform/classification_cache.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SvgConform
+  # Cache for requirement classification results
+  # Instance-level (per SaxValidationHandler) to avoid shared mutable state
+  # No mutexes needed - each handler has its own cache
+  class ClassificationCache
+    def initialize
+      @cache = {}
+    end
+
+    # Fetch from cache or compute the value
+    def fetch(key)
+      @cache[key] ||= yield
+    end
+
+    # Clear specific key or entire cache
+    def clear(key = nil)
+      if key
+        @cache.delete(key)
+      else
+        @cache.clear
+      end
+    end
+
+    # Return number of cached entries
+    def size
+      @cache.size
+    end
+
+    # Check if key exists in cache
+    def key?(key)
+      @cache.key?(key)
+    end
+  end
+end

data/lib/svg_conform/element_proxy.rb

@@ -32,15 +32,20 @@ module SvgConform
       @child_counters = {} # Track child element positions
     end
 
-    # Build full path ID for this element
+    # Build full path ID for this element (memoized for performance)
     def path_id
-      parts = @path + ["#{@name}[#{@position}]"]
-      "/#{parts.join('/')}"
+      @path_id ||= begin
+        parts = @path + ["#{@name}[#{@position}]"]
+        "/#{parts.join('/')}"
+      end
     end
 
-    # Return attributes as array of SaxAttribute objects (for compatibility)
+    # Return attributes as array of SaxAttribute objects (memoized for performance)
+    # Cached to avoid repeated object allocations during SAX parsing
     def attributes
-      @raw_attributes.map { |name, value| SaxAttribute.new(name, value) }
+      @attributes ||= @raw_attributes.map do |name, value|
+        SaxAttribute.new(name, value)
+      end
     end
 
     # Check if this element has a specific attribute
@@ -75,8 +80,8 @@ module SvgConform
         # Boolean check
         has_attribute?(method.to_s.chomp("?"))
       else
-        # Attribute access
-        @attributes[method.to_s] || @attributes[method.to_sym]
+        # Attribute access - use raw_attributes hash, not cached array
+        @raw_attributes[method.to_s] || @raw_attributes[method.to_sym]
       end
     end
 

data/lib/svg_conform/profile.rb

@@ -6,7 +6,12 @@ require_relative "remediations"
 
 module SvgConform
   # Base class for SVG validation profiles using lutaml-model serialization
+  #
+  # Profile acts as a factory for requirements and remediations.
+  # Each validation creates fresh instances to avoid state pollution.
   class Profile < Lutaml::Model::Serializable
+    PROFILES_DIR = File.expand_path("../../config/profiles", __dir__)
+
     attribute :name, :string
     attribute :description, :string
     attribute :import, :string

data/lib/svg_conform/profile_compiler.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "profile"
+
+module SvgConform
+  # Compiles and prepares SVG validation profiles
+  # Centralizes profile loading logic for better separation of concerns
+  class ProfileCompiler
+    @compile_cache = {}
+    @compile_mutex = Mutex.new
+
+    class << self
+      attr_reader :compile_cache, :compile_mutex
+
+      # Compile a profile by name
+      # Returns a cached profile if already compiled
+      def compile(profile_id)
+        profile_key = profile_id.to_s
+
+        # Check cache (thread-safe)
+        compile_mutex.synchronize do
+          return compile_cache[profile_key] if compile_cache[profile_key]
+        end
+
+        # Load and compile profile
+        profile = load_profile(profile_key)
+        compiled_profile = prepare_profile(profile)
+
+        # Cache result (thread-safe)
+        compile_mutex.synchronize do
+          compile_cache[profile_key] = compiled_profile
+        end
+
+        compiled_profile
+      end
+
+      # Compile from YAML content
+      def compile_from_yaml(yaml_content)
+        profile = Profile.from_yaml(yaml_content)
+        prepare_profile(profile)
+      end
+
+      # Compile from file path
+      def compile_from_file(file_path)
+        profile = Profile.load_from_file(file_path)
+        prepare_profile(profile)
+      end
+
+      # Clear compilation cache
+      def clear_cache!
+        compile_mutex.synchronize do
+          compile_cache.clear
+        end
+      end
+
+      private
+
+      # Load profile from profiles directory
+      def load_profile(profile_name)
+        profile_file = File.join(Profile::PROFILES_DIR, "#{profile_name}.yml")
+
+        unless File.exist?(profile_file)
+          raise ProfileError,
+                "Profile not found: #{profile_name} (expected: #{profile_file})"
+        end
+
+        Profile.load_from_file(profile_file)
+      end
+
+      # Prepare profile for use (validation and preprocessing)
+      def prepare_profile(profile)
+        # Validate profile has required fields
+        validate_profile(profile)
+
+        # Pre-compute requirement classifications for SAX validation
+        precompute_requirement_metadata(profile)
+
+        profile
+      end
+
+      # Validate profile structure
+      def validate_profile(profile)
+        if profile.name.nil? || profile.name.empty?
+          raise ProfileError,
+                "Profile must have a name"
+        end
+      end
+
+      # Pre-compute metadata for faster validation
+      def precompute_requirement_metadata(profile)
+        # Trigger requirement classification to populate caches
+        profile.requirements.each do |req|
+          # Access classification method to populate SaxValidationHandler cache
+          if req.respond_to?(:needs_deferred_validation?)
+            req.needs_deferred_validation?
+          end
+        end
+      end
+    end
+  end
+end