xsdvi 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbb88134a26f0713dea31aa8032d38e06fc8fe5e9b04b321211dd86fac4eadb5
-  data.tar.gz: 21cf471f50d28f47267af0cdd85a3733941e3dd23026389dd21b23fbfc6a7330
+  metadata.gz: 819798e045b576a5f2b55d8d80e6997c489c3d17988e30bbdace382be737f757
+  data.tar.gz: 7889f66439924400696c219fc0011f468580d56ad9a42a9cde21b0ef0d4995d0
 SHA512:
-  metadata.gz: 6c7d8578f22756bd8ae89f9f516da49a02ce926579a05fff307d244a47f8ff33dfc595c60d0fec04ba94412f722bad879da8500043f7af89bea870f10ad2ffff
-  data.tar.gz: 4a74687246d90e2136311111f5046fd768f9347115e2f22cb517adb922c932ca0c508efa0b5fa8ecf0cc8d09e671781b29f85594b31b52836baec98c58e9c76d
+  metadata.gz: 997ebdc3af70469940d70e129302edb19f8226be440c94cb7093520107a6ce02a6e8115c6912e9b8cd8a80239efd41f8cb6fcba88c791b40d8df7579024795d8
+  data.tar.gz: 27a2ae348887b91af15a75172bb2d42c643384c74b389645385541b81879e369eed9f9ec2f8bb99db8450fe8196fc7dc05f7eda5b5f38dfbbd705a8dae2a6027

data/README.adoc

@@ -27,7 +27,7 @@ Ruby projects.
 
 == Features
 
-=== XSD Component Visualization
+=== XSD component visualization
 
 * Elements and Attributes: Visual boxes showing element names, types, cardinality (min..max occurrences),  required/optional status, and namespace information
 * Compositors: Graphical representation of sequence (ordered), choice (alternatives), and all (unordered) element groups
@@ -35,7 +35,7 @@ Ruby projects.
 * Identity Constraints: Visualization of key, keyref, unique constraints with their selectors and fields
 * Type Information: Display of simple and complex type definitions, base types, and anonymous types
 
-=== Interactive SVG Output
+=== Interactive SVG output
 
 * Hierarchical Layout: Tree-structure visualization with proper indentation and connections
 * Collapsible/Expandable: JavaScript-enabled expand/collapse functionality for complex schemas (optional)
@@ -43,20 +43,21 @@ Ruby projects.
 * Documentation Display: Inline display of `<xs:documentation>` annotations
 * Color-coded Symbols: Different visual styles for elements, attributes, compositors, and constraints
 
-=== Flexible Output Options
+=== Flexible output options
 
 * Single Diagram: Generate one SVG showing the entire schema or a specific root element
 * Per-Element Diagrams: Generate separate SVG files for each top-level element
 * Custom Styling: Embed CSS in SVG files or use external stylesheets
 * Output Directory: Organize generated diagrams in custom folder structures
 
-=== Processing Capabilities
+=== Processing capabilities
 
 * Multiple XSD Files: Process multiple schema files in a single run
 * Loop Detection: Automatically detects and marks recursive element references
 * Namespace Handling: Properly displays and distinguishes multiple namespaces
 * Documentation Extraction: Extracts and formats XSD documentation for display
 * Large Schema Support: Handles complex, real-world schemas with hundreds of elements
+* Type Resolution: Comprehensive resolution of named types, group references, attribute groups, element references, and type inheritance (extension/restriction)
 
 == Installation
 
@@ -194,6 +195,104 @@ Creates `output/schema.svg` and `output/custom.css`, with the SVG referencing
 the external stylesheet. Useful for customizing diagram appearance.
 ====
 
+=== Comparing Java and Ruby outputs
+
+The `compare` command generates side-by-side visual comparisons of Java XsdVi
+v1.3 and Ruby XsdVi outputs. This is useful for validation, documentation, and
+visual quality assurance.
+
+==== Basic comparison
+
+[source,shell]
+----
+xsdvi compare schema.xsd
+----
+
+This command:
+
+1. Automatically downloads Java XsdVi JAR v1.3 (first run only, cached in `~/.xsdvi/`)
+2. Generates SVGs using both Java and Ruby implementations
+3. Extracts metadata and symbol counts from both outputs
+4. Creates an interactive HTML comparison page in `comparisons/<schema>-<timestamp>/`
+
+==== Comparison command options
+
+`-r, --root-node-name NAME`::
+Specify the schema root element to visualize (same as `generate` command). Use "all" to generate comparisons for all top-level elements.
+
+`-o, --output-path PATH`::
+Specify output directory for comparison files. Default: `comparisons/<schema>-<timestamp>/`
+
+`--skip-java`::
+Skip Java generation and use existing Java outputs. Useful when re-running comparison with updated Ruby code.
+
+`--skip-ruby`::
+Skip Ruby generation and use existing Ruby outputs. Useful for comparing against manually generated Ruby outputs.
+
+`-O, --open`::
+Automatically open the comparison HTML in your default browser after generation.
+
+==== Comparison examples
+
+.Basic comparison
+[example]
+====
+[source,shell]
+----
+xsdvi compare UnitsML-v1.0.xsd -r UnitsML
+----
+
+Downloads Java XsdVi (if needed), generates SVGs with both implementations, and creates an interactive comparison showing:
+
+* Side-by-side SVG iframes
+* Statistics table comparing file sizes and symbol counts
+* Generation time for each implementation
+* Visual diff highlighting any differences
+====
+
+.Compare all elements with auto-open
+[example]
+====
+[source,shell]
+----
+xsdvi compare schema.xsd -r all -O
+----
+
+Generates comparison for all top-level elements and automatically opens the comparison page in your browser. The HTML includes an element selector dropdown to switch between different element diagrams.
+====
+
+.Compare using existing Java output
+[example]
+====
+[source,shell]
+----
+xsdvi compare schema.xsd --skip-java -o my-comparison
+----
+
+Reuses existing Java output and generates fresh Ruby output, useful during Ruby development to quickly validate changes without regenerating Java outputs.
+====
+
+==== Comparison output structure
+
+After running a comparison, you get:
+
+[source]
+----
+comparisons/<schema>-<timestamp>/
+├── java/
+│   └── <schema>.svg         # Java XsdVi output
+├── ruby/
+│   └── <schema>.svg         # Ruby XsdVi output
+└── comparison.html          # Interactive comparison page
+----
+
+The comparison HTML displays:
+
+* **Statistics table**: File counts, sizes, symbol counts by type, generation times
+* **Visual indicators**: Green checkmarks for matches, red X for mismatches
+* **Split-screen view**: Java output (left) and Ruby output (right) in synchronized iframes
+* **Element selector**: Dropdown to switch between elements (when using `-r all`)
+
 ==  Architecture
 
 === Core components
@@ -231,15 +330,122 @@ options with built-in help and validation.
 ----
 XSD File → XsdHandler (Nokogiri parsing)
               ↓
-         Symbol Tree (TreeBuilder)
+         Type Registry Collection (complexTypes, simpleTypes, groups, etc.)
+              ↓
+         Symbol Tree Building (TreeBuilder with on-demand type resolution)
               ↓
   Symbol Processing (prepare_box, calculate dimensions)
               ↓
-      SVG Generation (Generator.draw)
+      SVG Generation (recursive drawing)
               ↓
          SVG File Output
 ----
 
+=== Type resolution architecture
+
+The type resolution system is the core feature that enables XSDVI to correctly process all XSD schema structures. It resolves references to named types, groups, and elements, and handles type inheritance patterns.
+
+==== Resolution mechanisms
+
+The system implements six resolution mechanisms:
+
+*Type Registry System*
+
+All named type and group definitions are collected during schema parsing into hash-based registries for O(1) lookup performance:
+
+* Complex types (`<xs:complexType name="...">`)
+* Simple types (`<xs:simpleType name="...">`)
+* Groups (`<xs:group name="...">`)
+* Attribute groups (`<xs:attributeGroup name="...">`)
+* Global elements (`<xs:element name="...">`)
+
+*Named Type Resolution*
+
+Resolves type references in element declarations:
+
+[source,xml]
+----
+<xs:element name="Foo" type="BarType"/>
+----
+
+The system:
+
+1. Strips namespace prefixes from type names
+2. Checks if the type is a W3C builtin (string, boolean, decimal, etc.)
+3. Looks up custom types in the complex/simple type registries
+4. Processes the resolved type definition inline
+
+*Group Reference Resolution*
+
+Resolves group references in compositors:
+
+[source,xml]
+----
+<xs:sequence>
+  <xs:group ref="CommonElements"/>
+</xs:sequence>
+----
+
+The referenced group's contents are expanded inline, maintaining proper tree hierarchy.
+
+*Attribute Group Reference Resolution*
+
+Resolves attribute group references:
+
+[source,xml]
+----
+<xs:complexType>
+  <xs:attributeGroup ref="CommonAttributes"/>
+</xs:complexType>
+----
+
+Supports nested attribute group references (recursive resolution).
+
+*Element Reference Resolution*
+
+Resolves element references with proper cardinality:
+
+[source,xml]
+----
+<xs:element ref="CommonElement" minOccurs="0" maxOccurs="unbounded"/>
+----
+
+The system preserves cardinality constraints while resolving to the element definition.
+
+*Extension and Restriction Processing*
+
+Handles type inheritance via `complexContent` and `simpleContent`:
+
+[source,xml]
+----
+<xs:complexType name="ExtendedType">
+  <xs:complexContent>
+    <xs:extension base="BaseType">
+      <xs:sequence>
+        <!-- Additional elements -->
+      </xs:sequence>
+    </xs:extension>
+  </xs:complexContent>
+</xs:complexType>
+----
+
+The system:
+
+1. Resolves the base type from registries
+2. Processes base type structure first (inherited elements/attributes)
+3. Processes extension-specific additions
+4. Maintains single inheritance hierarchy
+
+==== Performance characteristics
+
+* Registry collection: O(n) where n = total XSD nodes
+* Type lookup: O(1) hash access
+* Recursive resolution: Bounded by schema depth
+* Loop detection prevents infinite recursion
+* On-demand resolution (lazy evaluation)
+
+This architecture enables XSDVI to correctly process 100% of XSD schema structures, matching the Java version's capabilities.
+
 
 == Differences from Java version
 
@@ -295,6 +501,158 @@ Run rubocop:
 bundle exec rubocop
 ----
 
+=== Testing
+
+==== Test suite overview
+
+The XSDVI Ruby test suite provides comprehensive validation of all functionality with 46 tests across two categories:
+
+* **Integration tests** (14 tests): Validate complete end-to-end processing and compare outputs with Java version
+* **Type resolution tests** (32 tests): Validate all 7 type resolution mechanisms
+
+==== Running tests
+
+*Run all tests*
+
+[source,shell]
+----
+bundle exec rspec
+----
+
+*Run specific test file*
+
+[source,shell]
+----
+# Type resolution tests only
+bundle exec rspec spec/xsdvi/type_resolution_spec.rb
+
+# Output comparison tests only
+bundle exec rspec spec/xsdvi/output_comparison_spec.rb
+----
+
+*Run with documentation format*
+
+[source,shell]
+----
+bundle exec rspec --format documentation
+----
+
+*Run specific test group*
+
+[source,shell]
+----
+bundle exec rspec spec/xsdvi/type_resolution_spec.rb -e "Named Type Resolution"
+----
+
+==== Type resolution test coverage
+
+The type resolution test suite validates that XSDVI Ruby correctly processes all XSD schema constructs:
+
+*7 Resolution Mechanisms Tested:*
+
+1. **Named Type Resolution** - Complex and simple type references
+2. **Group Reference Resolution** - Model group (`<xs:group ref="...">`) expansion
+3. **Attribute Group Reference Resolution** - Attribute group references including nested
+4. **Element Reference Resolution** - Global element references with cardinality
+5. **Extension/Restriction Resolution** - Type inheritance via `complexContent`/`simpleContent`
+6. **Identity Constraint Resolution** - Key, keyref, unique, selector, field
+7. **Circular Reference Resolution** - Self-referencing and mutual circular references
+
+*Test Fixtures:*
+
+The test suite uses 7 XSD fixture files in `spec/fixtures/type_resolution/`:
+
+* `named_types.xsd` - Type reference resolution
+* `group_refs.xsd` - Group reference expansion
+* `attribute_groups.xsd` - Attribute group references
+* `element_refs.xsd` - Element references with cardinality
+* `inheritance.xsd` - Extension and restriction
+* `identity_constraints.xsd` - Key/keyref/unique constraints
+* `circular.xsd` - Circular reference handling
+
+For detailed test documentation, see `spec/xsdvi/TYPE_RESOLUTION_TESTING.md`.
+
+==== Generating comparison files
+
+To validate that XSDVI Ruby produces output identical to the Java version:
+
+*Generate Ruby output for UnitsML schema*
+
+[source,shell]
+----
+xsdvi generate spec/fixtures/UnitsML-v1.0-csd04.xsd -r UnitsML \
+  -p spec/fixtures/ruby
+----
+
+*Generate Ruby output for all elements*
+
+[source,shell]
+----
+xsdvi generate spec/fixtures/UnitsML-v1.0-csd04.xsd -r all -o \
+  -p spec/fixtures/ruby/all
+----
+
+*Generate Ruby output for TestXMLEntities*
+
+[source,shell]
+----
+xsdvi generate spec/fixtures/TestXMLEntities.xsd \
+  -p spec/fixtures/ruby
+----
+
+*Compare with Java version*
+
+The test suite automatically compares Ruby outputs with Java reference outputs in `spec/fixtures/java/`. The comparison normalizes known differences (text wrapping) and validates structural equivalence:
+
+[source,shell]
+----
+bundle exec rspec spec/xsdvi/output_comparison_spec.rb
+----
+
+*Manual comparison*
+
+You can manually compare outputs using diff tools:
+
+[source,shell]
+----
+# Compare UnitsML outputs
+diff spec/fixtures/java/UnitsML-v1.0-csd04.svg \
+     spec/fixtures/ruby/UnitsML-v1.0-csd04.svg
+
+# Compare specific element
+diff spec/fixtures/java/all/Quantity.svg \
+     spec/fixtures/ruby/all/Quantity.svg
+----
+
+Note: Direct diff will show text wrapping differences. Use the RSpec comparison tests for structural validation.
+
+*Generating fresh Java comparison files*
+
+If you need to regenerate Java version outputs (requires Java XsdVi):
+
+[source,shell]
+----
+# Assuming Java xsdvi.jar is available
+java -jar xsdvi.jar --in spec/fixtures/UnitsML-v1.0-csd04.xsd \
+     --root UnitsML --out spec/fixtures/java/UnitsML-v1.0-csd04.svg
+
+# For all elements
+java -jar xsdvi.jar --in spec/fixtures/UnitsML-v1.0-csd04.xsd \
+     --root all --one-node-only --out spec/fixtures/java/all
+----
+
+==== Test validation approach
+
+The test suite uses Canon gem for XML-aware comparison that:
+
+* Normalizes whitespace differences
+* Handles attribute ordering variations
+* Validates structural equivalence
+* Ignores text wrapping differences in `data-desc-*` attributes
+* Focuses on semantic correctness rather than byte-identical output
+
+This ensures that XSDVI Ruby produces functionally identical diagrams to the Java version while allowing minor presentational differences.
+
 == Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/lib/xsdvi/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "thor"
+require "fileutils"
 
 module Xsdvi
   # Command-line interface for XSDVI
@@ -67,16 +68,102 @@ module Xsdvi
       apply_style_settings(svg_generator, style_mode, options)
 
       inputs.each do |input|
-        process_input_file(
-          input,
-          xsd_handler,
-          svg_generator,
-          builder,
-          writer_helper,
-          root_node_name,
-          one_node_only,
-          output_path,
-        )
+        # Special handling for -r all: generate file for each element
+        if root_node_name == "all"
+          process_all_elements(
+            input,
+            xsd_handler,
+            svg_generator,
+            builder,
+            writer_helper,
+            output_path,
+          )
+        else
+          process_input_file(
+            input,
+            xsd_handler,
+            svg_generator,
+            builder,
+            writer_helper,
+            root_node_name,
+            one_node_only,
+            output_path,
+          )
+        end
+      end
+    end
+
+    desc "compare INPUT", "Compare Java and Ruby XsdVi outputs side-by-side"
+    method_option :root_node_name,
+                  type: :string,
+                  aliases: "-r",
+                  desc: "Schema root node name (or 'all' for all elements)"
+    method_option :output_path,
+                  type: :string,
+                  aliases: "-o",
+                  desc: "Output directory (default: ./comparisons/<name>-<timestamp>)"
+    method_option :skip_java,
+                  type: :boolean,
+                  default: false,
+                  desc: "Skip Java generation (use existing output)"
+    method_option :skip_ruby,
+                  type: :boolean,
+                  default: false,
+                  desc: "Skip Ruby generation (use existing output)"
+    method_option :open,
+                  type: :boolean,
+                  default: false,
+                  aliases: "-O",
+                  desc: "Open comparison HTML in browser automatically"
+    def compare(input)
+      unless File.exist?(input)
+        puts "Error: XSD file '#{input}' not found!"
+        exit(1)
+      end
+
+      puts "=" * 60
+      puts "XsdVi Comparison Tool"
+      puts "=" * 60
+      puts "Schema: #{input}"
+      puts ""
+
+      begin
+        generator = Comparison::DualGenerator.new(input, options)
+        result = generator.generate
+
+        puts ""
+        puts "=" * 60
+        puts "Comparison Complete!"
+        puts "=" * 60
+        puts ""
+        puts "Output directory: #{result[:output_dir]}"
+        puts "HTML comparison:  #{result[:html_file]}"
+        puts ""
+
+        if result[:java][:file_count] && result[:java][:generation_time] && result[:java][:generation_time]
+          puts "Java:  #{result[:java][:total_size_kb]} KB, " \
+               "#{result[:java][:file_count]} file(s), " \
+               "#{result[:java][:generation_time]}s"
+        end
+
+        if result[:ruby][:file_count] && result[:ruby][:generation_time] && result[:ruby][:generation_time]
+          puts "Ruby:  #{result[:ruby][:total_size_kb]} KB, " \
+               "#{result[:ruby][:file_count]} file(s), " \
+               "#{result[:ruby][:generation_time]}s"
+        end
+
+        puts ""
+
+        if options[:open]
+          open_in_browser(result[:html_file])
+        else
+          puts "Open #{result[:html_file]} in your browser to view the comparison"
+        end
+      rescue StandardError => e
+        puts ""
+        puts "Error: #{e.message}"
+        puts e.backtrace.first(5).join("\n") if ENV["DEBUG"]
+        exit(1)
       end
     end
 
@@ -84,6 +171,52 @@ module Xsdvi
 
     private
 
+    def process_all_elements(input, xsd_handler, svg_generator, builder,
+                             writer_helper, output_path)
+      # First, parse the schema to get all element names
+      doc = Nokogiri::XML(File.read(input))
+      element_names = xsd_handler.get_elements_names(doc)
+
+      if element_names.empty?
+        warn "No root elements found in schema!"
+        return
+      end
+
+      puts "Generating #{element_names.size} diagrams for all elements..."
+
+      # Generate a separate diagram for each element
+      element_names.each do |elem_name|
+        # Reset builder for each element
+        builder = Tree::Builder.new
+        xsd_handler = XsdHandler.new(builder)
+        xsd_handler.root_node_name = elem_name
+        xsd_handler.one_node_only = true
+        xsd_handler.set_schema_namespace(doc, elem_name)
+
+        # Process the schema with this specific root element
+        xsd_handler.process_file(input)
+
+        # Generate output filename
+        output_file = generate_output_filename(
+          input,
+          elem_name,
+          true, # one_node_only
+          output_path,
+        )
+
+        writer_helper.new_writer(output_file)
+
+        if builder.root
+          svg_generator.draw(builder.root)
+          puts "  Generated #{output_file}"
+        else
+          warn "  Skipped #{elem_name} (empty)"
+        end
+      end
+
+      puts "Done."
+    end
+
     def determine_style_mode(options)
       return :generate_style if options[:generate_style]
       return :use_style if options[:use_style]
@@ -159,5 +292,24 @@ module Xsdvi
         filename
       end
     end
+
+    def open_in_browser(file)
+      puts "Opening comparison in browser..."
+
+      # Get absolute path for browser
+      abs_path = File.expand_path(file)
+
+      case RbConfig::CONFIG["host_os"]
+      when /darwin/
+        system("open", abs_path)
+      when /linux/
+        system("xdg-open", abs_path)
+      when /mswin|mingw|cygwin/
+        system("start", abs_path)
+      else
+        puts "Unable to auto-open browser on this platform"
+        puts "Please open #{file} manually"
+      end
+    end
   end
 end