svg_conform 0.1.4 → 0.1.5

data/docs/reference_manifest.adoc

@@ -0,0 +1,370 @@
+= Reference Manifest and External Reference Handling
+:toc:
+:toclevels: 3
+
+== Overview
+
+The Reference Manifest provides a comprehensive view of all IDs and references in an SVG document, enabling consumers like Metanorma to make informed validation decisions about external references in their own context.
+
+== Architecture
+
+=== Reference Classification
+
+References are classified by validation scope:
+
+* **Internal References**: Can be validated by svg_conform (e.g., `#element-id`)
+* **External References**: Require consumer-level validation (e.g., URLs, URNs)
+
+.Reference Type Hierarchy
+[source]
+----
+BaseReference (abstract)
+├── InternalFragmentReference (#element-id)     - Internal validation
+├── DataUriReference (data:*)                   - Internal validation
+├── ExternalUrlReference (http://, https://)    - Consumer validation
+├── UrnReference (urn:*)                        - Consumer validation
+└── RelativePathReference (./path, /path)       - Consumer validation
+----
+
+=== ReferenceManifest Components
+
+The manifest provides complete context:
+
+* **Available IDs**: All IDs defined in the document
+* **Internal References**: Fragment identifiers referencing document IDs
+* **External References**: URLs, URNs, and paths requiring consumer validation
+
+== Usage
+
+=== Basic Usage
+
+[source,ruby]
+----
+require 'svg_conform'
+
+validator = SvgConform::Validator.new(profile: 'metanorma')
+result = validator.validate(svg_content)
+
+# Access the reference manifest
+manifest = result.reference_manifest
+
+# Check statistics
+stats = manifest.statistics
+puts "Total IDs: #{stats[:total_ids]}"
+puts "External references: #{stats[:external_references]}"
+----
+
+=== Accessing IDs
+
+[source,ruby]
+----
+# Get all defined IDs
+manifest.available_ids.each do |id_def|
+  puts "ID: #{id_def.id_value} on element #{id_def.element_name}"
+  puts "  at line #{id_def.line_number}" if id_def.line_number
+end
+
+# Check if specific ID exists
+if manifest.id_defined?('target-element')
+  puts "ID 'target-element' is defined"
+end
+----
+
+=== Accessing References
+
+[source,ruby]
+----
+# Get all internal references
+manifest.internal_references.each do |ref|
+  puts "Internal ref: #{ref.value} from #{ref.element_name}"
+end
+
+# Get all external references
+manifest.external_references.each do |ref|
+  puts "External ref: #{ref.value} from #{ref.element_name}"
+  puts "  Requires consumer validation"
+end
+
+# Get references by type
+manifest.references_by_type.each do |type, refs|
+  puts "#{type}: #{refs.size} references"
+end
+----
+
+=== Validating External References
+
+[source,ruby]
+----
+# Validate URN references in consumer context
+manifest.external_references
+  .select { |ref| ref.is_a?(SvgConform::References::UrnReference) }
+  .each do |urn_ref|
+    namespace = urn_ref.namespace
+
+    unless allowed_urn_namespaces.include?(namespace)
+      puts "Error: Disallowed URN namespace '#{namespace}'"
+      puts "  at line #{urn_ref.line_number}" if urn_ref.line_number
+    end
+  end
+
+# Validate external URLs
+manifest.external_references
+  .select { |ref| ref.is_a?(SvgConform::References::ExternalUrlReference) }
+  .each do |url_ref|
+    unless url_accessible?(url_ref.value)
+      puts "Warning: URL may be inaccessible: #{url_ref.value}"
+    end
+  end
+----
+
+=== Query Interface
+
+[source,ruby]
+----
+# Find references to a specific ID
+refs = manifest.references_to_id('target-element')
+puts "Found #{refs.size} references to 'target-element'"
+
+# Check for unresolved internal references
+unresolved = manifest.unresolved_internal_references
+if unresolved.any?
+  puts "Unresolved references:"
+  unresolved.each do |ref|
+    puts "  #{ref.value} at line #{ref.line_number}"
+  end
+end
+----
+
+=== Cross-Document Validation
+
+[source,ruby]
+----
+# Build manifests for multiple documents
+manifests = svg_files.map do |file|
+  result = validator.validate_file(file)
+  result.reference_manifest
+end
+
+# Validate cross-document references
+manifests.each do |manifest|
+  manifest.external_references.each do |ref|
+    # Parse reference like "other-doc.svg#element-42"
+    if ref.value =~ %r{^(.+\.svg)#(.+)$}
+      target_doc = $1
+      target_id = $2
+
+      # Find target manifest
+      target = manifests.find { |m| m.source_document.end_with?(target_doc) }
+
+      unless target&.id_defined?(target_id)
+        puts "Error: Cross-document reference to non-existent ID"
+        puts "  #{ref.value} at line #{ref.line_number}"
+      end
+    end
+  end
+end
+----
+
+=== Export Formats
+
+[source,ruby]
+----
+# Export as YAML for human inspection
+File.write('manifest.yml', result.export_manifest(format: :yaml))
+
+# Export as JSON for programmatic processing
+File.write('manifest.json', result.export_manifest(format: :json))
+
+# Get as Hash for in-memory processing
+manifest_hash = result.export_manifest(format: :hash)
+----
+
+== Reference Types
+
+=== InternalFragmentReference
+
+Internal SVG element references (e.g., `#element-id`).
+
+**Validation Scope**: Internal - validated by svg_conform
+
+**Methods**:
+
+* `target_id` - Returns the target ID without the `#` prefix
+
+[source,ruby]
+----
+ref = manifest.internal_references.first
+puts ref.target_id  # => "element-id" (without #)
+----
+
+=== ExternalUrlReference
+
+HTTP/HTTPS URL references.
+
+**Validation Scope**: External - requires consumer validation
+
+**Methods**:
+
+* `protocol` - Returns the URL protocol (`http` or `https`)
+
+[source,ruby]
+----
+ref = manifest.external_references.find { |r| r.is_a?(SvgConform::References::ExternalUrlReference) }
+puts ref.protocol  # => "https"
+----
+
+=== UrnReference
+
+URN (Uniform Resource Name) references (e.g., `urn:ietf:rfc:7996`).
+
+**Validation Scope**: External - requires consumer validation
+
+**Methods**:
+
+* `namespace` - Returns the URN namespace
+
+[source,ruby]
+----
+ref = manifest.external_references.find { |r| r.is_a?(SvgConform::References::UrnReference) }
+puts ref.namespace  # => "ietf"
+----
+
+=== RelativePathReference
+
+Relative path references (e.g., `./other.svg`, `/absolute/path.svg`).
+
+**Validation Scope**: External - requires consumer validation
+
+**Methods**:
+
+* `has_fragment?` - Returns true if reference includes fragment (`#`)
+* `path_component` - Returns path portion before fragment
+* `fragment_component` - Returns fragment portion after `#`
+
+[source,ruby]
+----
+ref = SvgConform::References::RelativePathReference.new(
+  value: "./other.svg#element"
+)
+puts ref.has_fragment?       # => true
+puts ref.path_component      # => "./other.svg"
+puts ref.fragment_component  # => "element"
+----
+
+=== DataUriReference
+
+Data URI references (e.g., `data:image/png;base64,iVBORw0KGgo=`).
+
+**Validation Scope**: Internal - validated by svg_conform
+
+**Methods**:
+
+* `media_type` - Returns the media type from data URI
+
+[source,ruby]
+----
+ref = manifest.internal_references.find { |r| r.is_a?(SvgConform::References::DataUriReference) }
+puts ref.media_type  # => "image/png"
+----
+
+== Integration with ValidationResult
+
+The manifest is automatically included in validation results:
+
+[source,ruby]
+----
+result = validator.validate(svg_content)
+
+# Convenience accessors
+result.available_ids              # All defined IDs
+result.internal_references        # Internal references
+result.external_references        # External references
+result.has_external_references?   # Boolean check
+result.unresolved_internal_references  # Broken internal refs
+result.reference_statistics       # Statistics hash
+
+# Export manifest
+result.export_manifest(format: :yaml)
+
+# Full result includes manifest
+result_hash = result.to_h
+puts result_hash[:reference_manifest]
+----
+
+== Metanorma Integration Example
+
+[source,ruby]
+----
+# Validate SVG document
+result = validator.validate(svg_content, profile: 'metanorma')
+
+# Get external references for consumer validation
+external_refs = result.external_references
+
+# Validate each reference type in Metanorma's context
+external_refs.each do |ref|
+  case ref
+  when SvgConform::References::UrnReference
+    # Validate URN resolves in Metanorma's registry
+    unless metanorma_urn_registry.resolve(ref.value)
+      metanorma_reporter.error(
+        "Unresolved URN: #{ref.value}",
+        line: ref.line_number
+      )
+    end
+
+  when SvgConform::References::ExternalUrlReference
+    # Optionally verify URL accessibility
+    if metanorma_config.verify_urls?
+      unless url_checker.accessible?(ref.value)
+        metanorma_reporter.warning(
+          "URL may not be accessible: #{ref.value}",
+          line: ref.line_number
+        )
+      end
+    end
+
+  when SvgConform::References::RelativePathReference
+    # Resolve relative path and verify file exists
+    resolved_path = resolve_relative_to_document(ref.value)
+    unless File.exist?(resolved_path)
+      metanorma_reporter.error(
+        "Referenced file not found: #{ref.value}",
+        line: ref.line_number
+      )
+    end
+  end
+end
+
+# Report summary
+puts "External references requiring validation: #{external_refs.size}"
+puts "By type: #{result.reference_statistics[:references_by_type]}"
+----
+
+== Benefits
+
+=== Complete Context
+
+The manifest provides both IDs and references, enabling comprehensive cross-validation.
+
+=== Consumer Control
+
+Consumers decide validation rules for external references based on their own context.
+
+=== Non-Breaking
+
+Existing svg_conform validation unchanged; external references reported but not errored.
+
+=== Type-Safe
+
+Strongly-typed reference objects with validation scope clearly defined.
+
+=== Extensible
+
+Easy to add new reference types without modifying existing code.
+
+== See Also
+
+* link:../EXTERNAL_REFERENCE_PROPOSAL.md[External Reference Architecture Proposal]
+* link:requirements.adoc[Requirements Documentation]
+* link:../config/profiles/metanorma.yml[Metanorma Profile Configuration]

data/docs/requirements.adoc

@@ -873,15 +873,82 @@ elements within the document.
 * link:remediation.adoc#invalid-id-references-remediation[InvalidIdReferencesRemediation]
 
 
+[[id-collection-requirement]]
+=== ID collection requirement
+
+==== General
+
+Collects all ID definitions in the document to build a comprehensive reference
+manifest for validation and consumer-level processing.
+
+Implemented as `IdCollectionRequirement`.
+
+==== Configuration options
+
+No configuration options. This requirement automatically collects all IDs during validation.
+
+==== Configuration
+
+.Example configuration of IdCollectionRequirement
+[example]
+====
+[source,yaml]
+----
+- id: "id_collection"
+  type: "IdCollectionRequirement"
+  description: "Collects all ID definitions for reference validation"
+----
+====
+
+==== Example from metanorma profile
+
+[example]
+====
+[source,yaml]
+----
+- id: "id_collection"
+  type: "IdCollectionRequirement"
+  description: "Collects all ID definitions for reference validation"
+----
+
+The metanorma profile uses this requirement as the first requirement to build
+the ID manifest before other requirements validate references.
+====
+
+==== Features
+
+* Tracks all ID definitions with location information (line/column numbers)
+* Builds reference manifest for cross-validation
+* Enables consumer-level validation of external references
+* Works in both DOM and SAX validation modes
+* Zero overhead - collects during normal traversal
+
+==== Related features
+
+* Reference Manifest - Complete context of IDs and references
+* Link Validation - Uses collected IDs for validation
+
+
 [[link-validation-requirement]]
 === Link validation requirement
 
 ==== General
 
-Validates that links use only ASCII characters (IETF requirement).
+Validates that links use only ASCII characters (IETF requirement) and classifies
+references by validation scope for consumer-level processing.
 
 Implemented as `LinkValidationRequirement`.
 
+==== Reference classification
+
+The requirement classifies references into types based on validation scope:
+
+* **Internal references**: Validated by svg_conform (e.g., `#element-id`, `data:` URIs)
+* **External references**: Deferred to consumer validation (e.g., URNs, URLs, relative paths)
+
+This enables consumers like Metanorma to validate external references in their
+own context rather than having svg_conform report them as errors.
+
 ==== Configuration options
 
 `ascii_only`:: Boolean flag to restrict links to ASCII characters. Default:

data/examples/document_input_demo.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "svg_conform"
+require "nokogiri"
+require "moxml"
+
+# Sample SVG content
+svg_content = <<~SVG
+  <?xml version="1.0" encoding="UTF-8"?>
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+    <defs>
+      <rect id="box" width="10" height="10"/>
+    </defs>
+    <use href="#box" x="20" y="20" fill="black"/>
+  </svg>
+SVG
+
+validator = SvgConform::Validator.new(mode: :sax)
+
+puts "=" * 60
+puts "SvgConform: Document Object Input Demo"
+puts "=" * 60
+
+# 1. String input (backward compatible)
+puts "\n1. String Input (Traditional)"
+puts "-" * 60
+result = validator.validate(svg_content, profile: :metanorma)
+puts "Valid: #{result.valid?}"
+puts "Errors: #{result.errors.size}"
+puts "Available IDs: #{result.available_ids.map(&:id_value).join(', ')}"
+
+# 2. Moxml Document input
+puts "\n2. Moxml Document Input"
+puts "-" * 60
+moxml_doc = Moxml.new.parse(svg_content)
+result = validator.validate(moxml_doc, profile: :metanorma)
+puts "Valid: #{result.valid?}"
+puts "Errors: #{result.errors.size}"
+puts "Available IDs: #{result.available_ids.map(&:id_value).join(', ')}"
+
+# 3. Moxml Element input
+puts "\n3. Moxml Element Input"
+puts "-" * 60
+moxml_element = moxml_doc.root
+result = validator.validate(moxml_element, profile: :metanorma)
+puts "Valid: #{result.valid?}"
+puts "Available IDs: #{result.available_ids.map(&:id_value).join(', ')}"
+
+# 4. Nokogiri Document input
+puts "\n4. Nokogiri Document Input"
+puts "-" * 60
+nokogiri_doc = Nokogiri::XML(svg_content)
+result = validator.validate(nokogiri_doc, profile: :metanorma)
+puts "Valid: #{result.valid?}"
+puts "Available IDs: #{result.available_ids.map(&:id_value).join(', ')}"
+
+# 5. Nokogiri Element input (Metanorma use case)
+puts "\n5. Nokogiri Element Input (Metanorma Integration)"
+puts "-" * 60
+nokogiri_element = nokogiri_doc.root
+puts "Element class: #{nokogiri_element.class.name}"
+result = validator.validate(nokogiri_element, profile: :metanorma)
+puts "Valid: #{result.valid?}"
+puts "Available IDs: #{result.available_ids.map(&:id_value).join(', ')}"
+
+# 6. Performance comparison
+puts "\n6. Performance Comparison"
+puts "-" * 60
+puts "Old way (metanorma):"
+puts "  nokogiri_element.to_xml  →  validator.validate(string)"
+puts "  = TWO conversions (serialize + parse)"
+puts
+puts "New way:"
+puts "  validator.validate(nokogiri_element)"
+puts "  = ONE conversion (serialize for SAX only)"
+puts
+puts "Benefit: 50% reduction in serialization/parsing overhead!"
+
+# 7. Reference manifest with document input
+puts "\n7. Reference Manifest from Document Objects"
+puts "-" * 60
+result = validator.validate(nokogiri_element, profile: :metanorma)
+manifest = result.reference_manifest
+
+puts "Total IDs defined: #{manifest.available_ids.size}"
+puts "Internal references: #{manifest.internal_references.size}"
+puts "External references: #{manifest.external_references.size}"
+
+if result.unresolved_internal_references.any?
+  puts "\nUnresolved references:"
+  result.unresolved_internal_references.each do |ref|
+    puts "  - #{ref.value}"
+  end
+else
+  puts "\nAll internal references resolved ✓"
+end
+
+puts "\n#{'=' * 60}"
+puts "Demo complete!"
+puts "=" * 60

data/lib/svg_conform/document.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "moxml"
+require "nokogiri" if defined?(Nokogiri)
 
 module SvgConform
   # Wrapper around Moxml document for SVG validation
@@ -28,6 +29,40 @@ module SvgConform
       new(content)
     end
 
+    # Create Document from an already-parsed node (Nokogiri or Moxml)
+    # Avoids re-parsing when input is already a DOM object
+    def self.from_node(node)
+      doc = allocate
+      doc.instance_variable_set(:@file_path, nil)
+      doc.instance_variable_set(:@xpath_cache, {})
+
+      # Convert node to Moxml document
+      if node.respond_to?(:to_xml) && node.class.name.start_with?("Moxml")
+        # Already a Moxml node, wrap it
+        doc.instance_variable_set(:@content, nil) # Don't store XML string
+        doc.instance_variable_set(:@moxml_document,
+                                  node.is_a?(Moxml::Document) ? node : wrap_moxml_element(node))
+      elsif defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Node)
+        # Nokogiri node - must serialize to convert to Moxml
+        # This is unavoidable due to different DOM implementations
+        xml_string = node.to_xml
+        doc.instance_variable_set(:@content, xml_string)
+        doc.send(:parse_document)
+      else
+        raise ArgumentError,
+              "Invalid input type: #{node.class}. Expected Moxml or Nokogiri DOM node."
+      end
+
+      doc
+    end
+
+    def self.wrap_moxml_element(element)
+      # If it's an element, we need to wrap it in a document
+      # For now, parse its XML representation
+      context = Moxml.new
+      context.parse(element.to_xml)
+    end
+
     def root
       @moxml_document.root
     end
@@ -55,6 +90,8 @@ module SvgConform
     end
 
     def to_xml
+      # Always generate from current moxml_document state
+      # This ensures modifications are reflected in the output
       @moxml_document.to_xml
     end
 
@@ -81,7 +118,9 @@ module SvgConform
     end
 
     def has_svg_namespace_prefix?
-      @content.include?("xmlns:svg=") || @content.include?("svg:")
+      # Check the current document state, not cached content
+      xml = @moxml_document.to_xml
+      xml.include?("xmlns:svg=") || xml.include?("svg:")
     end
 
     def has_viewbox?

data/lib/svg_conform/profile.rb

@@ -114,19 +114,25 @@ module SvgConform
     end
 
     def validate(document)
-      # Use SAX mode for validation performance
-      # Convert document to content string if it's a DOM document
+      # If it's a Document object, it's already loaded into DOM
+      # Use DOM validation (safe, already in memory)
       if document.is_a?(Document)
-        content = document.to_xml
-        sax_doc = SaxDocument.from_content(content)
-       return sax_doc.validate_with_profile(self)
+        context = ValidationContext.new(document, self)
+
+        # Validate using requirements system
+        requirements&.each do |requirement|
+          requirement.validate_document(document, context)
+        end
+
+        ValidationResult.new(document, self, context)
       elsif document.respond_to?(:to_xml)
-        # Handle any document-like object
+        # For other document objects, serialize and use SAX for safety
+        # (This handles Nokogiri/Moxml documents that aren't wrapped in Document)
         content = document.to_xml
         sax_doc = SaxDocument.from_content(content)
-        return sax_doc.validate_with_profile(self)
+        sax_doc.validate_with_profile(self)
       else
-        # Fallback to DOM mode for backward compatibility
+        # Fallback to DOM mode for non-serializable objects
         context = ValidationContext.new(document, self)
 
         # Validate using requirements system
@@ -134,7 +140,7 @@ module SvgConform
           requirement.validate_document(document, context)
         end
 
-        return ValidationResult.new(document, self, context)
+        ValidationResult.new(document, self, context)
       end
     end