svg_conform 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 509d5c50283abbefea59a0b96788976e4eeadf89664b337f035656be0545bd3e
-  data.tar.gz: 9e7825a05599868518fbe2626040f49cd94faa41647d4a46587d28d0bc999435
+  metadata.gz: a671b1d69dd6498470fc03cdaf2488bd3180187a39ef505cef2cb67d76de1725
+  data.tar.gz: c915d4ed0894b35293d78ea4a71f326e8985190dac8ae8df55c55b8eb10d1696
 SHA512:
-  metadata.gz: dbb90a922b23519170b187b0c4c1fa64e620333a8501d5f1d3e89318baf7eb163c4fc2131683a5b367775e9b31ec008c8db38cb9aa7a759d9a4806b882a33486
-  data.tar.gz: 13408a2c9d5a59fda73f42687d6b3235a854c2ea03fc4601343558cbad34b812ec1af5bb3c005766c43c33e516942580b39784b5b01c29ecf24f454f520062f8
+  metadata.gz: a32f6b36b517598e1a5f95612457c4e9a5386f64a15d6383dfb2e63052a2c58354a24afc730ad3a27b3ce6165c52447872e759655ef33ba8c546c12de2b16fbc
+  data.tar.gz: 1f22474906b51fe86cdeadac2817a66b2695bf7b1685370e25e058ed6c66dc9d09b2f95e26526b5a7937b493f2a7e51b3cf7a97b036c4ec0c8a7f7b0d1494801

data/.rubocop_todo.yml

@@ -1,93 +1,26 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-11-22 09:57:32 UTC using RuboCop version 1.81.1.
+# on 2025-11-26 09:22:57 UTC using RuboCop version 1.81.7.
 # 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: 3
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'lib/svg_conform/document.rb'
-    - 'lib/svg_conform/remediations/namespace_attribute_remediation.rb'
-
-# Offense count: 5
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleAlignWith.
 # SupportedStylesAlignWith: either, start_of_block, start_of_line
 Layout/BlockAlignment:
   Exclude:
     - 'spec/svg_conform/profiles/svg_1_2_rfc_profile_spec.rb'
-    - 'spec/svg_conform/requirements/id_reference_state_spec.rb'
-    - 'test_remove_ns.rb'
-    - 'test_reparse_ns.rb'
-    - 'test_string_remove_ns.rb'
 
-# Offense count: 3
-# This cop supports safe autocorrection (--autocorrect).
-Layout/BlockEndNewline:
-  Exclude:
-    - 'benchmark_validation.rb'
-    - 'spec/svg_conform/requirements/id_reference_state_spec.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
-Layout/ExtraSpacing:
-  Exclude:
-    - 'lib/svg_conform/document.rb'
-
-# Offense count: 7
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, AllowedPatterns.
-Layout/IndentationWidth:
-  Exclude:
-    - 'benchmark_validation.rb'
-    - 'spec/svg_conform/requirements/id_reference_state_spec.rb'
-    - 'test_remove_ns.rb'
-    - 'test_reparse_ns.rb'
-    - 'test_string_remove_ns.rb'
-
-# Offense count: 657
+# Offense count: 643
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowForAlignment, EnforcedStyleForExponentOperator, EnforcedStyleForRationalLiterals.
-# SupportedStylesForExponentOperator: space, no_space
-# SupportedStylesForRationalLiterals: space, no_space
-Layout/SpaceAroundOperators:
-  Exclude:
-    - 'debug_lucid_detailed.rb'
-    - 'debug_namespace_rem.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: final_newline, final_blank_line
-Layout/TrailingEmptyLines:
-  Exclude:
-    - 'examples/document_input_demo.rb'
-    - 'spec/svg_conform/validator_input_types_spec.rb'
-
-# Offense count: 5
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'debug_moxml_ns.rb'
-    - 'lib/svg_conform/document.rb'
-    - 'lib/svg_conform/remediations/namespace_attribute_remediation.rb'
-    - 'test_remove_ns.rb'
-
 # Offense count: 2
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
@@ -133,21 +66,6 @@ Lint/UnreachableCode:
   Exclude:
     - 'lib/svg_conform/commands/check.rb'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: IgnoreEmptyBlocks, AllowUnusedKeywordArguments.
-Lint/UnusedBlockArgument:
-  Exclude:
-    - 'benchmark_validation.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
-# NotImplementedExceptions: NotImplementedError
-Lint/UnusedMethodArgument:
-  Exclude:
-    - 'benchmark_validation.rb'
-
 # Offense count: 151
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
@@ -198,19 +116,6 @@ Performance/CollectionLiteralInLoop:
     - 'lib/svg_conform/batch_report.rb'
     - 'lib/svg_conform/compatibility/pattern_discovery.rb'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Performance/RedundantBlockCall:
-  Exclude:
-    - 'benchmark_validation.rb'
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: OnlySumOrWithInitialValue.
-Performance/Sum:
-  Exclude:
-    - 'benchmark_validation.rb'
-
 # Offense count: 9
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
@@ -260,19 +165,6 @@ Rake/MethodDefinitionInTask:
   Exclude:
     - 'lib/tasks/svgcheck.rake'
 
-# Offense count: 5
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
-# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
-# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
-# FunctionalMethods: let, let!, subject, watch
-# AllowedMethods: lambda, proc, it
-Style/BlockDelimiters:
-  Exclude:
-    - 'benchmark_validation.rb'
-    - 'spec/svg_conform/requirements/id_reference_state_spec.rb'
-    - 'spec/svg_conform/validator_input_types_spec.rb'
-
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, AllowComments.
@@ -289,28 +181,11 @@ Style/EmptyElse:
 Style/FormatStringToken:
   EnforcedStyle: unannotated
 
-# Offense count: 2
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: AllowedReceivers.
-# AllowedReceivers: Thread.current
-Style/HashEachMethods:
-  Exclude:
-    - 'benchmark_validation.rb'
-
 # Offense count: 1
 Style/MissingRespondToMissing:
   Exclude:
     - 'lib/svg_conform/cli.rb'
 
-# Offense count: 5
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
-# SupportedStyles: predicate, comparison
-Style/NumericPredicate:
-  Exclude:
-    - 'spec/**/*'
-    - 'benchmark_validation.rb'
-
 # Offense count: 4
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?
@@ -325,61 +200,3 @@ Style/OptionalBooleanParameter:
 Style/RedundantCondition:
   Exclude:
     - 'lib/svg_conform/external_checkers/svgcheck/parser.rb'
-
-# Offense count: 3
-# This cop supports safe autocorrection (--autocorrect).
-Style/RedundantParentheses:
-  Exclude:
-    - 'benchmark_validation.rb'
-
-# Offense count: 3
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: ConvertCodeThatCanStartToReturnNil, AllowedMethods, MaxChainLength.
-# AllowedMethods: present?, blank?, presence, try, try!
-Style/SafeNavigation:
-  Exclude:
-    - 'test_remove_ns.rb'
-    - 'test_reparse_ns.rb'
-    - 'test_string_remove_ns.rb'
-
-# Offense count: 6
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: Mode.
-Style/StringConcatenation:
-  Exclude:
-    - 'benchmark_validation.rb'
-    - 'examples/document_input_demo.rb'
-
-# Offense count: 23
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiterals:
-  Exclude:
-    - 'debug_lucid_detailed.rb'
-    - 'debug_lucid_test.rb'
-    - 'debug_moxml_attrs.rb'
-    - 'debug_moxml_ns.rb'
-    - 'debug_namespace_rem.rb'
-    - 'lib/svg_conform/document.rb'
-    - 'lib/svg_conform/remediations/namespace_attribute_remediation.rb'
-    - 'test_remove_ns.rb'
-    - 'test_reparse_ns.rb'
-    - 'test_string_remove_ns.rb'
-
-# Offense count: 6
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiteralsInInterpolation:
-  Exclude:
-    - 'benchmark_validation.rb'
-    - 'examples/document_input_demo.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleForMultiline.
-# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
-Style/TrailingCommaInHashLiteral:
-  Exclude:
-    - 'benchmark_validation.rb'

data/Gemfile

@@ -5,8 +5,8 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in svg_conform.gemspec
 gemspec
 
-gem "canon"
-gem "openssl"
+gem "canon", "~>0.1.10"
+gem "openssl", "~> 3.0"
 gem "rake"
 gem "rspec"
 gem "rubocop"

data/README.adoc

@@ -124,6 +124,31 @@ Each remediation action can be linked to a particular requirement to indicate
 their relationship, defined in the profile.
 
 
+=== Two-mode architecture
+
+SvgConform uses two distinct operating modes for optimal performance and functionality:
+
+**SAX Validation Mode** (always used for validation):
+
+* Memory-safe streaming XML parser
+* Constant memory usage regardless of file size
+* Handles files of any size (tested with 100MB+ files)
+* Read-only - cannot modify documents
+
+**DOM Remediation Mode** (only when applying fixes):
+
+* Full document tree loaded in memory
+* XPath queries and tree modification
+* Memory scales with file size
+* Only used when `fix: true` option is specified
+
+This architecture ensures validation is always safe for large files, while modifications
+are only performed when explicitly requested and necessary.
+
+See link:docs/sax_validation_mode.adoc[SAX Validation Mode Guide] for details on
+writing SAX-compatible requirements.
+
+
 === Reporting
 
 SvgConform provides detailed reporting on SVG conformance issues.
@@ -142,7 +167,6 @@ profile conformance tools.
 See <<external_compliance>> for details.
 
 
-
 == Usage
 
 === Installation
@@ -172,7 +196,9 @@ $ gem install svg_conform
 === Command line usage
 
 Details and examples of command line usage can be found in
-<<command_line_interface>>.
+link:docs/cli_guide.adoc[CLI Guide].
+
+==== Quick start
 
 List available profiles:
 
@@ -202,11 +228,16 @@ Batch process a directory of SVG files:
 $ svg_conform check --directory=images/ --profile=metanorma -f --output-dir=fixed/
 ----
 
+For comprehensive CLI documentation including all options, workflows, and troubleshooting,
+see link:docs/cli_guide.adoc[CLI Guide].
+
 
 === Ruby API usage
 
 Details and examples of Ruby API usage can be found in
-<<ruby_api_reference>>.
+link:docs/api_reference.adoc[API Reference].
+
+==== Quick start
 
 [source,ruby]
 ----
@@ -280,6 +311,9 @@ Benefits:
 - **Safe for large files**: Always uses memory-efficient SAX parsing
 - **Backward compatible**: String input still works as before
 
+For comprehensive API documentation including all classes, methods, advanced usage,
+and integration patterns, see link:docs/api_reference.adoc[API Reference].
+
 
 === Reference manifest
 
@@ -315,521 +349,6 @@ end
 See link:docs/reference_manifest.adoc[Reference Manifest Documentation] for complete details.
 
 
-[[command_line_interface]]
-== Command line interface
-
-The `svg_conform` command-line tool provides validation and remediation capabilities for SVG files.
-
-=== Basic commands
-
-==== List available profiles
-
-[source,bash]
-----
-$ svg_conform profiles
-----
-
-Show detailed information about profiles:
-
-[source,bash]
-----
-$ svg_conform profiles --verbose
-----
-
-==== Validate a single SVG file
-
-[source,bash]
-----
-$ svg_conform check file.svg --profile=metanorma
-----
-
-Options:
-
-* `--profile=PROFILE` or `-p`: Profile to validate against (default: `svg_1_2_rfc`)
-* `--format=FORMAT`: Output format: `table` (default), `json`, or `yaml`
-* `--output=FILE` or `-o`: Save report to file
-
-Example with JSON output:
-
-[source,bash]
-----
-$ svg_conform check file.svg -p metanorma --format=json --output=report.json
-----
-
-==== Fix a single SVG file
-
-Apply automatic remediations to fix conformance issues:
-
-[source,bash]
-----
-$ svg_conform check file.svg --profile=metanorma --fix
-----
-
-Specify custom output file:
-
-[source,bash]
-----
-$ svg_conform check file.svg -p metanorma -f --fix-output=fixed.svg
-----
-
-Options:
-
-* `--fix` or `-f`: Enable automatic remediation
-* `--fix-output=FILE`: Output file for remediated SVG (default: `FILE.fixed.svg`)
-
-==== Process multiple files
-
-Process multiple SVG files at once:
-
-[source,bash]
-----
-$ svg_conform check file1.svg file2.svg file3.svg --profile=metanorma
-----
-
-With remediation, an output directory is required:
-
-[source,bash]
-----
-$ svg_conform check *.svg -p metanorma --fix --output-dir=fixed/
-----
-
-==== Process a directory
-
-Recursively process all SVG files in a directory:
-
-[source,bash]
-----
-$ svg_conform check --directory=images/ --profile=metanorma
-----
-
-With remediation:
-
-[source,bash]
-----
-$ svg_conform check -d images/ -p metanorma --fix --output-dir=fixed/
-----
-
-Replace files in-place (use with caution):
-
-[source,bash]
-----
-$ svg_conform check -d images/ -p metanorma --fix --in-place --force
-----
-
-==== Batch processing options
-
-Additional options for batch processing:
-
-* `--quiet` or `-q`: Suppress per-file output, show summary only
-* `--verbose` or `-v`: Show detailed progress
-* `--report-format=FORMAT`: Generate detailed report in `json` or `yaml`
-* `--report-output=FILE`: Save detailed batch report to file
-* `--manifest=FILE`: Generate manifest mapping original to remediated files (default: `manifest.json`)
-
-Example with detailed reporting:
-
-[source,bash]
-----
-$ svg_conform check -d images/ -p metanorma -f --output-dir=fixed/ \
-  --report-format=json --report-output=batch-report.json \
-  --manifest=file-mapping.json
-----
-
-==== Display version
-
-[source,bash]
-----
-$ svg_conform version
-----
-
-=== Exit codes
-
-* `0`: All files valid or successfully remediated
-* `1`: Validation failures or errors occurred
-
-=== Common workflows
-
-==== Quality control workflow
-
-Check all SVG files before deployment:
-
-[source,bash]
-----
-$ svg_conform check -d assets/images/ -p metanorma --quiet
-----
-
-==== Batch remediation workflow
-
-Fix all non-conforming files:
-
-[source,bash]
-----
-# 1. Validate and identify issues
-$ svg_conform check -d images/ -p metanorma --report-format=json \
-  --report-output=pre-fix-report.json
-
-# 2. Apply fixes
-$ svg_conform check -d images/ -p metanorma --fix --output-dir=fixed/ \
-  --manifest=manifest.json
-
-# 3. Verify fixes
-$ svg_conform check -d fixed/ -p metanorma --report-format=json \
-  --report-output=post-fix-report.json
-----
-
-==== Integration with CI/CD
-
-Validate SVGs in continuous integration:
-
-[source,bash]
-----
-$ svg_conform check -d docs/images/ -p metanorma --quiet
-
-# Exit code 0 = pass, 1 = fail
-----
-
-=== Complete reference
-
-See link:docs/cli_guide.adoc[CLI Guide] for comprehensive documentation including:
-
-* All available profiles and their requirements
-* Detailed option descriptions
-* Advanced usage patterns
-* Troubleshooting common issues
-* Integration examples
-
-
-[[ruby_api_reference]]
-== Ruby API reference
-
-The SvgConform Ruby API provides programmatic access to SVG validation and remediation.
-
-=== Basic validation
-
-==== Using the validator
-
-[source,ruby]
-----
-require 'svg_conform'
-
-validator = SvgConform::Validator.new
-result = validator.validate(svg_content, profile: :metanorma)
-
-puts "Valid: #{result.valid?}"
-puts "Errors: #{result.errors.count}"
-puts "Warnings: #{result.warnings.count}"
-
-# Access error details
-result.errors.each do |error|
-  puts "#{error.requirement_id}: #{error.message}"
-  puts "  Location: #{error.element}" if error.element
-end
-----
-
-==== Loading profiles
-
-Load a profile by name:
-
-[source,ruby]
-----
-profile = SvgConform::Profiles.get(:svg_1_2_rfc)
-----
-
-Available built-in profiles:
-
-* `:base` - Minimal SVG validation
-* `:svg_1_2_rfc` - RFC 7996 compliance (IETF XMLRFC documents)
-* `:svg_1_2_rfc_with_rdf` - RFC 7996 with RDF metadata support
-* `:metanorma` - Metanorma document requirements
-* `:lucid` - Lucid profile
-* `:no_external_css` - Disallow external CSS
-
-Load a custom profile from file:
-
-[source,ruby]
-----
-profile = SvgConform::Profile.load_from_file('path/to/profile.yml')
-----
-
-==== Validating with profiles
-
-[source,ruby]
-----
-profile = SvgConform::Profiles.get(:metanorma)
-document = SvgConform::Document.new(svg_content)
-result = profile.validate(document)
-
-if result.valid?
-  puts "SVG is valid!"
-else
-  puts "Found #{result.errors.count} errors"
-end
-----
-
-=== Applying remediations
-
-==== Basic remediation
-
-[source,ruby]
-----
-profile = SvgConform::Profiles.get(:metanorma)
-document = SvgConform::Document.from_file('input.svg')
-
-# Apply all remediations defined in the profile
-changes = profile.apply_remediations(document)
-
-puts "Applied #{changes.length} remediations"
-
-# Save the remediated SVG
-File.write('output.svg', document.to_xml)
-----
-
-==== Using the remediation runner
-
-For more control over the remediation process:
-
-[source,ruby]
-----
-profile = SvgConform::Profiles.get(:metanorma)
-runner = SvgConform::RemediationRunner.new(profile: profile)
-
-# Run remediation on a file
-result = runner.run_remediation_file('input.svg')
-
-if result.success?
-  File.write('output.svg', result.remediated_content)
-  puts "Fixed #{result.issues_fixed} issues"
-  puts "Final validation: #{result.final_validation.valid?}"
-else
-  puts "Remediation failed: #{result.error.message}"
-end
-----
-
-==== Checking available remediations
-
-[source,ruby]
-----
-profile = SvgConform::Profiles.get(:metanorma)
-
-puts "Profile has #{profile.remediation_count} remediations available"
-
-profile.remediations.each do |remediation|
-  puts "- #{remediation.class.name}"
-end
-----
-
-=== Working with documents
-
-==== Creating documents
-
-From a string:
-
-[source,ruby]
-----
-document = SvgConform::Document.new(svg_string)
-----
-
-From a file:
-
-[source,ruby]
-----
-document = SvgConform::Document.from_file('path/to/file.svg')
-----
-
-From a DOM node (Nokogiri or Moxml):
-
-[source,ruby]
-----
-nokogiri_element = Nokogiri::XML(svg_string).root
-document = SvgConform::Document.from_node(nokogiri_element)
-----
-
-==== Document operations
-
-[source,ruby]
-----
-# Access the underlying DOM
-root = document.root
-elements = document.find_all('//svg:rect')
-
-# Check for specific elements
-has_viewbox = document.root.attribute?('viewBox')
-
-# Modify the document
-document.root.set_attribute('width', '500')
-
-# Serialize to XML
-xml_string = document.to_xml
-----
-
-=== Reference manifest
-
-==== Accessing the manifest
-
-[source,ruby]
-----
-result = validator.validate(svg_content, profile: :metanorma)
-manifest = result.reference_manifest
-
-# Get all defined IDs
-manifest.available_ids.each do |id_def|
-  puts "ID: #{id_def.id_value}"
-  puts "  Element: #{id_def.element_name}"
-  puts "  Line: #{id_def.line_number}"
-end
-----
-
-==== Checking references
-
-[source,ruby]
-----
-# Check for unresolved internal references
-if result.has_unresolved_references?
-  puts "Unresolved references found:"
-  result.unresolved_internal_references.each do |ref|
-    puts "  #{ref.value} at line #{ref.line_number}"
-  end
-end
-
-# Check for external references
-if result.has_external_references?
-  puts "External references:"
-  result.external_references.each do |ref|
-    puts "  #{ref.value} (#{ref.reference_type})"
-  end
-end
-----
-
-==== Reference types
-
-The manifest classifies references by type:
-
-[source,ruby]
-----
-manifest.internal_references.each do |ref|
-  case ref.reference_type
-  when 'url'
-    puts "URL reference: #{ref.value}"
-  when 'fragment'
-    puts "Fragment reference: #{ref.value}"
-  when 'fill'
-    puts "Fill attribute: #{ref.value}"
-  when 'href'
-    puts "Href attribute: #{ref.value}"
-  end
-end
-----
-
-=== Advanced usage
-
-==== Custom validation context
-
-[source,ruby]
-----
-context = SvgConform::ValidationContext.new(
-  document: document,
-  profile: profile
-)
-
-# Run specific requirements
-requirement = SvgConform::Requirements::ViewboxRequiredRequirement.new
-errors = requirement.check(context)
-----
-
-==== Batch processing
-
-[source,ruby]
-----
-validator = SvgConform::Validator.new
-results = {}
-
-Dir.glob('images/**/*.svg').each do |file|
-  result = validator.validate_file(file, profile: :metanorma)
-  results[file] = result
-end
-
-# Summary
-valid_count = results.count { |_, r| r.valid? }
-puts "#{valid_count}/#{results.size} files are valid"
-----
-
-==== Report generation
-
-[source,ruby]
-----
-# Create a conformance report
-report = SvgConform::ConformanceReport.from_svg_conform_result(
-  "file.svg",
-  result,
-  profile: :metanorma
-)
-
-# Export as JSON
-json_output = report.to_json
-File.write('report.json', json_output)
-
-# Export as YAML
-yaml_output = report.to_yaml
-File.write('report.yaml', yaml_output)
-----
-
-=== API classes
-
-==== Core classes
-
-* `SvgConform::Validator` - Main validation interface
-* `SvgConform::Profile` - Profile definition and management
-* `SvgConform::Document` - SVG document wrapper
-* `SvgConform::ValidationResult` - Validation result container
-* `SvgConform::RemediationRunner` - Remediation execution
-
-==== Requirement classes
-
-Located in `SvgConform::Requirements`:
-
-* `AllowedElementsRequirement` - Element whitelist validation
-* `ColorRestrictionsRequirement` - Color format restrictions
-* `FontFamilyRequirement` - Font family restrictions
-* `ForbiddenContentRequirement` - Forbidden element/attribute check
-* `IdReferenceRequirement` - ID reference validation
-* `InvalidIdReferencesRequirement` - Invalid reference detection
-* `LinkValidationRequirement` - Link validation
-* `NamespaceRequirement` - Namespace validation
-* `NamespaceAttributesRequirement` - Namespace attribute check
-* `NoExternalCssRequirement` - External CSS prohibition
-* `NoExternalFontsRequirement` - External font prohibition
-* `NoExternalImagesRequirement` - External image prohibition
-* `StylePromotionRequirement` - Presentation attribute check
-* `StyleRequirement` - Style attribute validation
-* `ViewboxRequiredRequirement` - ViewBox requirement
-
-==== Remediation classes
-
-Located in `SvgConform::Remediations`:
-
-* `ColorRemediation` - Fix color format issues
-* `FontRemediation` - Fix font family issues
-* `FontEmbeddingRemediation` - Embed external fonts
-* `ImageEmbeddingRemediation` - Embed external images
-* `InvalidIdReferencesRemediation` - Fix invalid references
-* `NamespaceRemediation` - Fix namespace issues
-* `NamespaceAttributeRemediation` - Remove namespace attributes
-* `NoExternalCssRemediation` - Convert external CSS
-* `StylePromotionRemediation` - Promote presentation attributes
-* `ViewboxRemediation` - Add missing ViewBox
-
-=== Complete reference
-
-See link:docs/api_reference.adoc[API Reference] for comprehensive documentation including:
-
-* Complete class hierarchy
-* Detailed method signatures
-* Parameter descriptions
-* Return value specifications
-* Integration patterns
-* Advanced examples
-
-
 [[external_compliance]]
 == External compliance
 
@@ -841,6 +360,25 @@ SvgConform provides compatibility with existing SVG validation tools:
 See link:docs/compatibility.adoc[Compatibility Documentation] for details.
 
 
+== Documentation
+
+=== User documentation
+
+* link:docs/cli_guide.adoc[CLI Guide] - Comprehensive command-line usage
+* link:docs/api_reference.adoc[API Reference] - Complete Ruby API documentation
+* link:docs/profiles.adoc[Profile Documentation] - Profile system and built-in profiles
+* link:docs/requirements.adoc[Requirements Reference] - All validation requirements
+* link:docs/remediation.adoc[Remediation Reference] - All automatic remediations
+* link:docs/reference_manifest.adoc[Reference Manifest] - ID and reference tracking
+* link:docs/rdf_metadata_support.adoc[RDF Metadata Support] - RDF/Dublin Core configuration
+
+=== Developer documentation
+
+* link:docs/sax_validation_mode.adoc[SAX Validation Mode] - Writing SAX-compatible requirements
+* link:CONTINUATION_PLAN.md[Development Plan] - Project roadmap and tasks
+* link:IMPLEMENTATION_STATUS.md[Implementation Status] - Component status tracking
+
+
 == Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.

data/docs/reference_manifest.adoc

@@ -363,8 +363,9 @@ Strongly-typed reference objects with validation scope clearly defined.
 
 Easy to add new reference types without modifying existing code.
 
-== See Also
+== Additional resources
 
-* link:../EXTERNAL_REFERENCE_PROPOSAL.md[External Reference Architecture Proposal]
 * link:requirements.adoc[Requirements Documentation]
+* link:api_reference.adoc[API Reference]
+* link:../README.adoc[Main README]
 * link:../config/profiles/metanorma.yml[Metanorma Profile Configuration]

data/lib/svg_conform/document.rb

@@ -92,7 +92,28 @@ module SvgConform
     def to_xml
       # Always generate from current moxml_document state
       # This ensures modifications are reflected in the output
-      @moxml_document.to_xml
+      xml = @moxml_document.to_xml
+
+      # Clean up unused namespace declarations if marked by remediations
+      if instance_variable_defined?(:@unused_namespace_prefixes)
+        prefixes = @unused_namespace_prefixes
+        xml = remove_namespace_declarations(xml, prefixes) if prefixes && !prefixes.empty?
+        # Clear the marker after cleanup
+        remove_instance_variable(:@unused_namespace_prefixes)
+      end
+
+      xml
+    end
+
+    def remove_namespace_declarations(xml, prefixes)
+      # Remove xmlns:prefix="uri" declarations from the XML string
+      # This works around Moxml/Nokogiri's inability to remove namespace declarations
+      prefixes.reduce(xml) do |result, prefix|
+        # Match xmlns:prefix="..." with various quote styles and surrounding whitespace
+        # The pattern matches: xmlns:prefix="uri" or xmlns:prefix='uri'
+        # It captures leading whitespace to remove it too
+        result.gsub(%r{\s+xmlns:#{prefix}=["'][^"']*["']}, "")
+      end
     end
 
     def dup

data/lib/svg_conform/node_helpers.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SvgConform
+  # Shared helper methods for working with XML nodes
+  #
+  # This module provides common utilities used by both requirements
+  # and remediations to avoid code duplication and ensure consistency.
+  module NodeHelpers
+    # Check if a node is an element
+    # @param node [Object] the node to check
+    # @return [Boolean] true if the node is an element
+    def element?(node)
+      node.respond_to?(:name) && !node.name.nil?
+    end
+
+    # Check if a node is text
+    # @param node [Object] the node to check
+    # @return [Boolean] true if the node is text
+    def text?(node)
+      node.respond_to?(:text?) && node.text?
+    end
+
+    # Get attribute value from a node
+    # @param node [Object] the node
+    # @param name [String] attribute name
+    # @return [String, nil] attribute value or nil
+    def get_attribute(node, name)
+      return nil unless node.respond_to?(:[])
+
+      node[name]
+    end
+
+    # Set attribute value on a node
+    # @param node [Object] the node
+    # @param name [String] attribute name
+    # @param value [String] attribute value
+    # @return [Boolean] true if successful
+    def set_attribute(node, name, value)
+      return unless node.respond_to?(:[]=)
+
+      node[name] = value
+      true
+    end
+
+    # Check if node has an attribute
+    # @param node [Object] the node
+    # @param name [String] attribute name
+    # @return [Boolean] true if attribute exists
+    def has_attribute?(node, name)
+      return false unless node.respond_to?(:[])
+
+      !node[name].nil?
+    end
+
+    # Remove attribute from a node
+    # @param node [Object] the node
+    # @param name [String] attribute name
+    # @return [Boolean] true if successful
+    def remove_attribute(node, name)
+      if node.respond_to?(:remove_attribute)
+        node.remove_attribute(name)
+        true
+      elsif node.respond_to?(:[]=) && node.respond_to?(:[])
+        # Fallback for bracket notation
+        node[name] = nil
+        true
+      else
+        false
+      end
+    end
+  end
+end

data/lib/svg_conform/remediations/base_remediation.rb

@@ -2,11 +2,14 @@
 
 require "lutaml/model"
 require_relative "../remediation_result"
+require_relative "../node_helpers"
 
 module SvgConform
   module Remediations
     # Base class for all remediations using lutaml-model serialization
     class BaseRemediation < Lutaml::Model::Serializable
+      include SvgConform::NodeHelpers
+
       attribute :id, :string
       attribute :description, :string
       attribute :targets, :string, collection: true
@@ -72,27 +75,8 @@ module SvgConform
 
       protected
 
-      def element?(node)
-        node.respond_to?(:name) && node.name
-      end
-
-      def get_attribute(node, attr_name)
-        return nil unless node.respond_to?(:[])
-
-        node[attr_name]
-      end
-
-      def set_attribute(node, attr_name, value)
-        return unless node.respond_to?(:[]=)
-
-        node[attr_name] = value
-      end
-
-      def has_attribute?(node, attr_name)
-        return false unless node.respond_to?(:[])
-
-        !node[attr_name].nil?
-      end
+      # Helper methods for node manipulation included via NodeHelpers module:
+      # element?, text?, get_attribute, set_attribute, has_attribute?, remove_attribute
 
       def find_nodes(document, &)
         nodes = []
@@ -100,20 +84,6 @@ module SvgConform
         nodes
       end
 
-      # Helper method to remove attribute
-      def remove_attribute(node, name)
-        if node.respond_to?(:remove_attribute)
-          node.remove_attribute(name)
-          true
-        elsif node.respond_to?(:[]=) && node.respond_to?(:[])
-          # Fallback for different implementations
-          node[name] = nil
-          true
-        else
-          false
-        end
-      end
-
       # Helper method to remove node
       def remove_node(node)
         return false unless node.respond_to?(:remove)

data/lib/svg_conform/remediations/namespace_remediation.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "base_remediation"
+require "set"
 
 module SvgConform
   module Remediations
@@ -105,6 +106,11 @@ module SvgConform
           remove_node(node)
         end
 
+        # Clean up unused namespace declarations
+        # Note: Moxml/Nokogiri don't support removing namespace declarations directly,
+        # so we mark the document for post-processing during serialization
+        cleanup_unused_namespace_declarations(document)
+
         changes
       end
 
@@ -146,6 +152,60 @@ module SvgConform
         # Same logic as find_namespace_uri_for_prefix
         find_namespace_uri_for_prefix(node, prefix)
       end
+
+      def cleanup_unused_namespace_declarations(document)
+        # Find which namespace prefixes are still in use
+        used_prefixes = find_used_namespace_prefixes(document)
+
+        # Get the root element
+        root = document.respond_to?(:root) ? document.root : document
+        return unless root.respond_to?(:namespace_definitions)
+
+        # Get disallowed namespace prefixes
+        disallowed_prefixes = root.namespace_definitions.filter_map do |ns|
+          prefix = ns.respond_to?(:prefix) ? ns.prefix : nil
+          # Extract namespace URI from Moxml::Namespace object
+          uri = ns.respond_to?(:uri) ? ns.uri : nil
+          next if prefix.nil? || prefix.empty? # Skip default namespace
+          next if allowed_namespaces.include?(uri) # Keep allowed namespaces
+
+          next if used_prefixes.include?(prefix) # Keep prefixes still in use
+
+          prefix
+        end
+
+        # Store the prefixes to remove on the document for later serialization
+        # Try to store on Document wrapper first, fallback to moxml_document
+        target = document.respond_to?(:instance_variable_set) ? document : root.document
+        target&.instance_variable_set(:@unused_namespace_prefixes, disallowed_prefixes)
+      end
+
+      def find_used_namespace_prefixes(document)
+        used_prefixes = Set.new(["xml"]) # xml prefix is always reserved
+
+        document.traverse do |node|
+          next unless node.respond_to?(:name)
+
+          # Check element name for namespace prefix
+          if node.name.include?(":")
+            prefix = node.name.split(":").first
+            used_prefixes << prefix
+          end
+
+          # Check attributes for namespace prefixes
+          if node.respond_to?(:attributes)
+            node.attributes.each do |attr|
+              attr_name = attr.respond_to?(:name) ? attr.name : attr.to_s
+              if attr_name.include?(":")
+                prefix = attr_name.split(":").first
+                used_prefixes << prefix
+              end
+            end
+          end
+        end
+
+        used_prefixes
+      end
     end
   end
 end

data/lib/svg_conform/requirements/base_requirement.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "../node_helpers"
+
 module SvgConform
   module Requirements
     # Base class for all validation requirements
     class BaseRequirement < Lutaml::Model::Serializable
+      include SvgConform::NodeHelpers
+
       attribute :id, :string
       attribute :description, :string
       attribute :type, :string, polymorphic_class: true, default: -> {
@@ -65,48 +69,8 @@ module SvgConform
         true
       end
 
-      # Helper method to check if a node is an element
-      def element?(node)
-        node.respond_to?(:name) && !node.name.nil?
-      end
-
-      # Helper method to check if a node is text
-      def text?(node)
-        node.respond_to?(:text?) && node.text?
-      end
-
-      # Helper method to get attribute value
-      def get_attribute(node, name)
-        return nil unless node.respond_to?(:attribute)
-
-        attr = node.attribute(name)
-        attr&.value
-      end
-
-      # Helper method to set attribute value
-      def set_attribute(node, name, value)
-        return false unless node.respond_to?(:set_attribute)
-
-        node.set_attribute(name, value)
-        true
-      end
-
-      # Helper method to remove attribute
-      def remove_attribute(node, name)
-        return false unless node.respond_to?(:remove_attribute)
-
-        node.remove_attribute(name)
-        true
-      end
-
-      # Helper method to check if attribute exists
-      def has_attribute?(node, name)
-        return false unless node.respond_to?(:attribute)
-
-        !node.attribute(name).nil?
-      end
-
       # Helper method to get all attributes
+      # Note: Other attribute helpers are included via NodeHelpers module
       def get_attributes(node)
         return {} unless node.respond_to?(:attributes)
 

data/lib/svg_conform/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SvgConform
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

data/svg_conform.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "lutaml-model", "~> 0.7"
-  spec.add_dependency "moxml"
+  spec.add_dependency "moxml", "~> 0.1", ">= 0.1.10"
   spec.add_dependency "table_tennis"
   spec.add_dependency "thor"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: svg_conform
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-22 00:00:00.000000000 Z
+date: 2026-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -28,16 +28,22 @@ dependencies:
   name: moxml
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.10
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.10
 - !ruby/object:Gem::Dependency
   name: table_tennis
   requirement: !ruby/object:Gem::Requirement
@@ -138,6 +144,7 @@ files:
 - lib/svg_conform/external_checkers/svgcheck/validation_pipeline.rb
 - lib/svg_conform/fast_document_analyzer.rb
 - lib/svg_conform/fixer.rb
+- lib/svg_conform/node_helpers.rb
 - lib/svg_conform/node_index_builder.rb
 - lib/svg_conform/profile.rb
 - lib/svg_conform/profiles.rb