xseed 1.0.0

data/lib/xseed/documentation/presentation/navigation_builder.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Xseed
+  module Documentation
+    module Presentation
+      # Generates navigation sidebar (Table of Contents) for HTML documentation
+      # Ports functionality from XS3P navigation.xsl
+      class NavigationBuilder
+        def initialize(parser, config)
+          @parser = parser
+          @config = config
+        end
+
+        def generate
+          builder = Nokogiri::HTML::Builder.new do |html|
+            html.nav(id: "toc") do
+              html.ul(class: "nav nav-list xs3p-sidenav") do
+                generate_toc_items(html)
+              end
+            end
+          end
+          builder.to_html
+        end
+
+        private
+
+        def generate_toc_items(html)
+          # Schema properties
+          html.li do
+            html.strong do
+              html.a("Schema Document Properties", href: "#SchemaProperties")
+            end
+          end
+
+          # Generate component sections based on sorting preference
+          if @config.sort_by_component
+            generate_sorted_components(html)
+          else
+            generate_unsorted_components(html)
+          end
+
+          # Glossary (if enabled)
+          return unless @config.print_glossary
+
+          html.li do
+            html.strong do
+              html.a("Glossary", href: "#Glossary")
+            end
+          end
+        end
+
+        def generate_sorted_components(html)
+          # Elements
+          if @parser.elements.any?
+            generate_component_section(html, @parser.elements, "Elements",
+                                       "#SchemaElements")
+          end
+
+          # Complex Types
+          if @parser.complex_types.any?
+            generate_component_section(html, @parser.complex_types,
+                                       "Complex Types", "#SchemaComplexTypes")
+          end
+
+          # Groups
+          if @parser.groups.any?
+            generate_component_section(html, @parser.groups, "Groups",
+                                       "#SchemaGroups")
+          end
+
+          # Simple Types
+          if @parser.simple_types.any?
+            generate_component_section(html, @parser.simple_types, "Types",
+                                       "#SchemaSimpleTypes")
+          end
+
+          # Attribute Groups
+          return unless @parser.attribute_groups.any?
+
+          generate_component_section(html, @parser.attribute_groups,
+                                     "Attribute Groups", "#SchemaAttributeGroups")
+        end
+
+        def generate_unsorted_components(html)
+          html.li do
+            html.strong do
+              html.a("Global Schema Components", href: "#SchemaComponents")
+            end
+          end
+
+          # Generate all components in order they appear
+          all_components = []
+          if @parser.attribute_groups.any?
+            all_components.concat(@parser.attribute_groups)
+          end
+          if @parser.complex_types.any?
+            all_components.concat(@parser.complex_types)
+          end
+          all_components.concat(@parser.elements) if @parser.elements.any?
+          all_components.concat(@parser.groups) if @parser.groups.any?
+          if @parser.simple_types.any?
+            all_components.concat(@parser.simple_types)
+          end
+
+          all_components.each do |component|
+            generate_component_link(html, component)
+          end
+        end
+
+        def generate_component_section(html, components, title, anchor)
+          return if components.empty?
+
+          html.li do
+            html.strong do
+              html.a(title, href: anchor)
+            end
+
+            html.ul(class: "nav nav-list nav-list-#{title.downcase.tr(' ',
+                                                                      '-')}") do
+              sorted_components = components.sort_by { |c| c["name"] || "" }
+              sorted_components.each do |component|
+                generate_component_link(html, component)
+              end
+            end
+          end
+        end
+
+        def generate_component_link(html, component)
+          component_name = component["name"]
+          return unless component_name
+
+          component_type = component.name
+          component_id = generate_component_id(component_type, component_name)
+
+          html.li(class: "nav-sub-item") do
+            html.a(href: "##{component_id}") do
+              html.strong component_name
+            end
+          end
+        end
+
+        def generate_component_id(component_type, component_name)
+          type_name = case component_type
+                      when "element"
+                        "element"
+                      when "complexType"
+                        "complex-type"
+                      when "simpleType"
+                        "simple-type"
+                      when "group"
+                        "model-group"
+                      when "attributeGroup"
+                        "attribute-group"
+                      when "attribute"
+                        "attribute"
+                      when "notation"
+                        "notation"
+                      else
+                        component_type.downcase
+                      end
+
+          "#{type_name}-#{component_name}"
+        end
+      end
+    end
+  end
+end

data/lib/xseed/documentation/schema_loader.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "lutaml/xsd"
+require "nokogiri"
+
+module Xseed
+  module Documentation
+    # Wrapper around Lutaml::Xsd for loading and parsing XSD schemas
+    #
+    # This class provides a simple interface to lutaml-xsd's schema parsing
+    # capabilities, with Xseed-specific error handling and configuration.
+    #
+    # @example Load a schema from file
+    #   schema = SchemaLoader.load("path/to/schema.xsd")
+    #   puts schema.target_namespace
+    #
+    # @example Parse schema content with mappings
+    #   schema = SchemaLoader.parse(
+    #     xsd_content,
+    #     location: "/path/to/schemas",
+    #     schema_mappings: [
+    #       { from: "common.xsd", to: "/local/common.xsd" }
+    #     ]
+    #   )
+    #
+    class SchemaLoader
+      # Error raised when schema file cannot be loaded
+      class LoadError < StandardError; end
+
+      # Error raised when schema content cannot be parsed
+      class ParseError < StandardError; end
+
+      # Load an XSD schema from a file
+      #
+      # @param file_path [String] Path to the XSD file
+      # @param config [Config] Optional configuration for schema mappings
+      # @return [Lutaml::Xsd::Schema] Parsed schema object
+      # @raise [LoadError] if file cannot be read
+      # @raise [ParseError] if schema cannot be parsed
+      def self.load(file_path, config: nil)
+        content = File.read(file_path)
+        location = File.dirname(File.expand_path(file_path))
+
+        parse(content, location: location, config: config)
+      rescue Errno::ENOENT
+        raise LoadError, "Schema file not found: #{file_path}"
+      rescue ParseError => e
+        raise e
+      rescue StandardError => e
+        raise ParseError, "Failed to load schema: #{e.message}"
+      end
+
+      # Parse XSD schema content
+      #
+      # @param content [String] XSD schema content
+      # @param location [String] Base directory or URL for resolving imports
+      # @param schema_mappings [Array<Hash>] Schema location mappings
+      # @param config [Config] Optional configuration for additional mappings
+      # @return [Lutaml::Xsd::Schema] Parsed schema object
+      # @raise [ParseError] if schema cannot be parsed
+      def self.parse(content, location: nil, schema_mappings: nil, config: nil)
+        # Validate that it's actually an XSD schema
+        validate_schema_content(content)
+
+        mappings = build_mappings(schema_mappings, config)
+
+        # Use lutaml-xsd's parse method
+        Lutaml::Xsd.parse(
+          content,
+          location: location,
+          schema_mappings: mappings,
+        )
+      rescue Nokogiri::XML::SyntaxError => e
+        raise ParseError, "Invalid XML syntax: #{e.message}"
+      rescue StandardError => e
+        raise ParseError, "Failed to parse schema: #{e.message}"
+      end
+
+      # Validate that content is an XSD schema document
+      #
+      # @param content [String] XML content to validate
+      # @raise [ParseError] if not a valid schema
+      def self.validate_schema_content(content)
+        doc = Nokogiri::XML(content)
+        root = doc.root
+
+        raise ParseError, "Empty or invalid XML document" unless root
+
+        # Check if root element is xs:schema or xsd:schema
+        unless root.name == "schema" &&
+            root.namespace&.href&.include?("XMLSchema")
+          raise ParseError,
+                "Not a valid XSD schema: root element must be xs:schema"
+        end
+      rescue Nokogiri::XML::SyntaxError => e
+        raise ParseError, "Invalid XML syntax: #{e.message}"
+      end
+
+      # Build schema location mappings from various sources
+      #
+      # @param explicit_mappings [Array<Hash>] Explicitly provided mappings
+      # @param config [Config] Configuration object with potential mappings
+      # @return [Array<Hash>] Combined schema location mappings
+      def self.build_mappings(explicit_mappings, config)
+        mappings = []
+
+        # Add explicit mappings if provided
+        mappings.concat(explicit_mappings) if explicit_mappings
+
+        # Add config-based mappings if available
+        if config.respond_to?(:schema_mappings)
+          mappings.concat(config.schema_mappings)
+        end
+
+        mappings.empty? ? nil : mappings
+      end
+
+      private_class_method :build_mappings, :validate_schema_content
+    end
+  end
+end

data/lib/xseed/documentation/utils/helpers.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Xseed
+  module Documentation
+    module Utils
+      # Helpers utility module for common formatting and component utilities
+      #
+      # This module provides methods for formatting schema component descriptions,
+      # generating anchor IDs, formatting occurrences, URIs, boolean values, and
+      # various XSD-specific sets.
+      #
+      # Based on XS3P common-helpers.xsl utilities.
+      module Helpers
+        # Component type prefixes for anchor IDs
+        COMPONENT_PREFIXES = {
+          "attribute" => "attr-",
+          "attributeGroup" => "attrgrp-",
+          "complexType" => "ctype-",
+          "element" => "elem-",
+          "group" => "grp-",
+          "notation" => "nota-",
+          "simpleType" => "stype-",
+          "key" => "key-",
+          "unique" => "key-",
+        }.freeze
+
+        # Returns a human-readable description for a schema component type
+        #
+        # @param component_type [String] The component type (e.g., "element", "complexType")
+        # @return [String] Human-readable description
+        #
+        # @example
+        #   component_description("element")     #=> "Element"
+        #   component_description("complexType") #=> "Complex Type"
+        def component_description(component_type)
+          case component_type
+          when "attribute" then "Attribute"
+          when "attributeGroup" then "Attribute Group"
+          when "complexType" then "Complex Type"
+          when "element" then "Element"
+          when "simpleType" then "Simple Type"
+          when "group" then "Model Group"
+          when "notation" then "Notation"
+          when "all" then "All Model Group"
+          when "choice" then "Choice Model Group"
+          when "sequence" then "Sequence Model Group"
+          else "Unknown Component"
+          end
+        end
+
+        # Generates a unique anchor ID for a schema component
+        #
+        # @param component_type [String] The component type
+        # @param name [String, nil] The component name
+        # @return [String] The generated anchor ID
+        #
+        # @example
+        #   generate_component_id("element", "Person") #=> "elem-Person"
+        #   generate_component_id("schema", nil)       #=> "schema"
+        def generate_component_id(component_type, name)
+          return "schema" if component_type == "schema"
+
+          prefix = COMPONENT_PREFIXES[component_type] || "comp-"
+          "#{prefix}#{name}"
+        end
+
+        # Formats min/max occurrences as [min..max]
+        #
+        # @param min_occurs [Integer, String, nil] Minimum occurrences (default: 1)
+        # @param max_occurs [Integer, String, nil] Maximum occurrences (default: 1)
+        # @return [String] Formatted occurrence string
+        #
+        # @example
+        #   format_occurs(1, 1)           #=> "[1]"
+        #   format_occurs(0, "unbounded") #=> "[0..*]"
+        #   format_occurs(1, 5)           #=> "[1..5]"
+        def format_occurs(min_occurs, max_occurs)
+          min = min_occurs.nil? ? 1 : min_occurs.to_i
+          max = if max_occurs == "unbounded"
+                  "*"
+                elsif max_occurs.nil?
+                  1
+                else
+                  max_occurs.to_i
+                end
+
+          if min == 1 && max == 1
+            "[1]"
+          else
+            "[#{min}..#{max}]"
+          end
+        end
+
+        # Formats a URI, creating a clickable link for HTTP/HTTPS URIs
+        #
+        # @param uri [String, nil] The URI to format
+        # @return [String] Formatted URI (HTML link or plain text)
+        #
+        # @example
+        #   format_uri("http://example.com")
+        #   #=> "<a href=\"http://example.com\" title=\"http://example.com\">http://example.com</a>"
+        #
+        #   format_uri("schema.xsd")
+        #   #=> "schema.xsd"
+        def format_uri(uri)
+          return "" if uri.nil? || uri.empty?
+
+          if uri.start_with?("http://", "https://")
+            escaped_uri = CGI.escape_html(uri)
+            "<a href=\"#{escaped_uri}\" title=\"#{escaped_uri}\">#{escaped_uri}</a>"
+          else
+            uri
+          end
+        end
+
+        # Formats a boolean value as "yes" or "no"
+        #
+        # @param value [Boolean, String, Integer, nil] The boolean value
+        # @return [String] "yes" or "no"
+        #
+        # @example
+        #   format_boolean(true)    #=> "yes"
+        #   format_boolean("true")  #=> "yes"
+        #   format_boolean(1)       #=> "yes"
+        #   format_boolean(false)   #=> "no"
+        #   format_boolean(nil)     #=> "no"
+        def format_boolean(value)
+          return "no" if value.nil?
+
+          normalized = value.to_s.downcase.strip
+          if %w[true 1].include?(normalized)
+            "yes"
+          else
+            "no"
+          end
+        end
+
+        # Formats a block attribute set, expanding #all
+        #
+        # @param value [String, nil] The block value
+        # @return [String] Formatted block set
+        #
+        # @example
+        #   format_block_set("#all")
+        #   #=> "restriction, extension, substitution"
+        #
+        #   format_block_set("restriction")
+        #   #=> "restriction"
+        def format_block_set(value)
+          return "" if value.nil? || value.strip.empty?
+
+          if value.strip == "#all"
+            "restriction, extension, substitution"
+          else
+            value
+          end
+        end
+
+        # Formats a derivation set, expanding #all
+        #
+        # @param value [String, nil] The derivation value
+        # @return [String] Formatted derivation set
+        #
+        # @example
+        #   format_derivation_set("#all")
+        #   #=> "restriction, extension"
+        #
+        #   format_derivation_set("restriction")
+        #   #=> "restriction"
+        def format_derivation_set(value)
+          return "" if value.nil? || value.strip.empty?
+
+          if value.strip == "#all"
+            "restriction, extension"
+          else
+            value
+          end
+        end
+
+        # Formats a simple type derivation set, expanding #all
+        #
+        # @param value [String, nil] The derivation value
+        # @return [String] Formatted simple derivation set
+        #
+        # @example
+        #   format_simple_derivation_set("#all")
+        #   #=> "restriction, list, union"
+        #
+        #   format_simple_derivation_set("restriction")
+        #   #=> "restriction"
+        def format_simple_derivation_set(value)
+          return "" if value.nil? || value.strip.empty?
+
+          if value.strip == "#all"
+            "restriction, list, union"
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/xseed/documentation/utils/namespaces.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Xseed
+  module Documentation
+    module Utils
+      # Namespaces utility module for handling XSD namespace prefixes
+      #
+      # This module provides methods for formatting namespace prefixes,
+      # generating links to namespace declarations, and collecting namespace
+      # information from XML Schemas.
+      #
+      # Based on XS3P namespaces.xsl utilities.
+      module Namespaces
+        # Formats a namespace prefix with a trailing colon
+        #
+        # @param prefix [String, nil] The namespace prefix
+        # @return [String] The formatted prefix with colon, or empty string
+        #
+        # @example
+        #   format_namespace_prefix("xs")  #=> "xs:"
+        #   format_namespace_prefix("")    #=> ""
+        #   format_namespace_prefix(nil)   #=> ""
+        def format_namespace_prefix(prefix)
+          return "" if prefix.nil? || prefix.strip.empty?
+
+          "#{prefix}:"
+        end
+
+        # Generates an HTML link to a namespace declaration
+        #
+        # @param prefix [String, nil] The namespace prefix
+        # @param schema [Object] The schema object with namespaces hash
+        # @param schema_loc [String] Optional schema location for external refs
+        # @return [String] HTML link element or plain text
+        #
+        # @example
+        #   namespace_link("xs", schema)
+        #   #=> "<a href=\"#ns-xs\" title=\"...\">xs</a>"
+        def namespace_link(prefix, schema, schema_loc: nil)
+          return "" if prefix.nil? || prefix.strip.empty?
+
+          namespaces = schema&.namespaces || {}
+
+          if namespaces.key?(prefix)
+            # Known namespace - create link to declaration
+            href = if schema_loc && schema_loc != "this"
+                     "#{schema_loc}##{namespace_anchor_id(prefix)}"
+                   else
+                     "##{namespace_anchor_id(prefix)}"
+                   end
+
+            namespace_uri = namespaces[prefix]
+            title = "Find out namespace of '#{prefix}' prefix: #{namespace_uri}"
+
+            "<a href=\"#{CGI.escape_html(href)}\" " \
+              "title=\"#{CGI.escape_html(title)}\">#{CGI.escape_html(prefix)}</a>"
+          else
+            # Unknown namespace - create warning link
+            warning = "Unknown namespace prefix: #{prefix}"
+            "<a href=\"javascript:void(0)\" " \
+              "onclick=\"alert('#{CGI.escape_html(warning)}')\" " \
+              "title=\"#{CGI.escape_html(warning)}\">#{CGI.escape_html(prefix)}</a>"
+          end
+        end
+
+        # Formats a namespace prefix with optional link and colon
+        #
+        # @param prefix [String, nil] The namespace prefix
+        # @param schema [Object] The schema object with namespaces hash
+        # @param link [Boolean] Whether to generate a link (default: true)
+        # @param schema_loc [String] Optional schema location for external refs
+        # @return [String] Formatted prefix with colon, optionally linked
+        #
+        # @example
+        #   format_namespace_with_prefix("xs", schema)
+        #   #=> "<a href=\"#ns-xs\" title=\"...\">xs</a>:"
+        #
+        #   format_namespace_with_prefix("xs", schema, link: false)
+        #   #=> "xs:"
+        def format_namespace_with_prefix(prefix, schema, link: true,
+                                         schema_loc: nil)
+          return "" if prefix.nil? || prefix.strip.empty?
+
+          if link
+            "#{namespace_link(prefix, schema, schema_loc: schema_loc)}:"
+          else
+            format_namespace_prefix(prefix)
+          end
+        end
+
+        # Collects all namespaces from a schema
+        #
+        # @param schema [Object, nil] The schema object with namespaces hash
+        # @return [Hash] Hash of prefix => namespace URI mappings
+        #
+        # @example
+        #   collect_namespaces(schema)
+        #   #=> { "xs" => "http://www.w3.org/2001/XMLSchema",
+        #   #     "tns" => "http://example.com/target" }
+        def collect_namespaces(schema)
+          return {} if schema.nil?
+
+          namespaces = schema.namespaces
+          return {} if namespaces.nil?
+
+          namespaces.dup
+        end
+
+        # Generates an anchor ID for a namespace prefix
+        #
+        # @param prefix [String, nil] The namespace prefix
+        # @return [String] The anchor ID for the namespace
+        #
+        # @example
+        #   namespace_anchor_id("xs")  #=> "ns-xs"
+        #   namespace_anchor_id("tns") #=> "ns-tns"
+        def namespace_anchor_id(prefix)
+          "ns-#{prefix}"
+        end
+
+        # Formats a namespace declaration (xmlns)
+        #
+        # @param prefix [String, nil] The namespace prefix (empty for default)
+        # @param namespace [String, nil] The namespace URI
+        # @return [String] Formatted xmlns declaration
+        #
+        # @example
+        #   format_namespace_declaration("xs", "http://www.w3.org/2001/XMLSchema")
+        #   #=> "xmlns:xs=\"http://www.w3.org/2001/XMLSchema\""
+        #
+        #   format_namespace_declaration("", "http://example.com/default")
+        #   #=> "xmlns=\"http://example.com/default\""
+        def format_namespace_declaration(prefix, namespace)
+          prefix_part = if prefix.nil? || prefix.strip.empty?
+                          "xmlns"
+                        else
+                          "xmlns:#{prefix}"
+                        end
+
+          namespace_value = namespace.nil? ? "" : CGI.escape_html(namespace)
+
+          "#{prefix_part}=\"#{namespace_value}\""
+        end
+      end
+    end
+  end
+end