xseed 1.0.0

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Xseed
+  module Documentation
+    module Utils
+      # References utility module for handling XSD component references
+      #
+      # This module provides methods for extracting component names, prefixes,
+      # and namespaces from qualified and unqualified references in XML Schema.
+      #
+      # Based on XS3P references.xsl utilities.
+      module References
+        XSD_NAMESPACE = "http://www.w3.org/2001/XMLSchema"
+
+        # Extracts the local name from a reference
+        #
+        # @param ref [String, nil] The reference string (e.g., "xs:string" or "SimpleType")
+        # @return [String] The local name part of the reference
+        #
+        # @example
+        #   get_ref_name("xs:string")  #=> "string"
+        #   get_ref_name("SimpleType") #=> "SimpleType"
+        #   get_ref_name(nil)          #=> ""
+        def get_ref_name(ref)
+          return "" if ref.nil? || ref.empty?
+
+          if ref.include?(":")
+            # Extract local name after first colon
+            ref.split(":", 2).last
+          else
+            # No prefix, return as-is
+            ref
+          end
+        end
+
+        # Extracts the namespace prefix from a reference
+        #
+        # @param ref [String, nil] The reference string (e.g., "xs:string")
+        # @return [String] The namespace prefix or empty string if none
+        #
+        # @example
+        #   get_ref_prefix("xs:string")  #=> "xs"
+        #   get_ref_prefix("SimpleType") #=> ""
+        #   get_ref_prefix(nil)          #=> ""
+        def get_ref_prefix(ref)
+          return "" if ref.nil? || ref.empty?
+
+          if ref.include?(":")
+            # Extract prefix before first colon
+            ref.split(":", 2).first
+          else
+            # No prefix
+            ""
+          end
+        end
+
+        # Resolves the namespace URI from a reference prefix
+        #
+        # @param ref [String, nil] The reference string (e.g., "xs:string")
+        # @param schema [Object] The schema object with namespaces hash
+        # @return [String, nil] The resolved namespace URI or nil
+        #
+        # @example
+        #   get_ref_namespace("xs:string", schema) #=> "http://www.w3.org/2001/XMLSchema"
+        #   get_ref_namespace("SimpleType", schema) #=> nil
+        def get_ref_namespace(ref, schema)
+          return nil if ref.nil? || ref.empty? || schema.nil?
+
+          prefix = get_ref_prefix(ref)
+          return nil if prefix.empty?
+
+          schema.namespaces[prefix]
+        end
+
+        # Returns the declared prefix of the schema's target namespace
+        #
+        # @param schema [Object] The schema object with target_namespace and namespaces
+        # @return [String] The prefix for the target namespace or empty string
+        #
+        # @example
+        #   get_this_prefix(schema) #=> "tns"
+        def get_this_prefix(schema)
+          return "" if schema.nil? || schema.target_namespace.nil?
+
+          target_ns = schema.target_namespace
+          namespaces = schema.namespaces || {}
+
+          # Find the prefix that maps to the target namespace
+          prefix = namespaces.find { |_k, v| v == target_ns }&.first
+          prefix || ""
+        end
+
+        # Returns the declared prefix of the XML Schema namespace
+        #
+        # @param schema [Object] The schema object with namespaces hash
+        # @return [String] The prefix for XSD namespace or empty string
+        #
+        # @example
+        #   get_xsd_prefix(schema) #=> "xs" or "xsd"
+        def get_xsd_prefix(schema)
+          return "" if schema.nil?
+
+          namespaces = schema.namespaces || {}
+
+          # Find the prefix that maps to the XSD namespace
+          prefix = namespaces.find { |_k, v| v == XSD_NAMESPACE }&.first
+          prefix || ""
+        end
+
+        # Resolves a type reference to its components
+        #
+        # @param ref [String, nil] The type reference (e.g., "xs:string" or "MyType")
+        # @param schema [Object] The schema object with namespaces
+        # @return [Hash] Hash with :namespace, :prefix, and :local_name keys
+        #
+        # @example
+        #   resolve_type_ref("xs:string", schema)
+        #   #=> { namespace: "http://www.w3.org/2001/XMLSchema",
+        #   #     prefix: "xs", local_name: "string" }
+        def resolve_type_ref(ref, schema)
+          if ref.nil? || ref.empty?
+            return { namespace: nil, prefix: "",
+                     local_name: "" }
+          end
+
+          {
+            namespace: get_ref_namespace(ref, schema),
+            prefix: get_ref_prefix(ref),
+            local_name: get_ref_name(ref),
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Xseed
+  module Documentation
+    module Utils
+      # String manipulation utilities
+      # Ported from xs3p utils/strings.xsl
+      module Strings
+        # Translates occurrences of single and double quotes with escape
+        # characters
+        #
+        # @param text [String] Text to translate
+        # @return [String] Text with escaped quotes
+        def self.escape_quotes(text)
+          return text if text.nil? || text.empty?
+
+          # Escape single quotes
+          result = text.gsub("'", "\\\\'")
+          # Escape double quotes
+          result.gsub('"', '\\\\"')
+        end
+
+        # Repeatedly output content
+        #
+        # @param content [String] The content to be output
+        # @param count [Integer] Number of times to output the content
+        # @return [String] Repeated content
+        def self.repeat(content, count)
+          return "" if count <= 0
+
+          content * count
+        end
+
+        # Translates occurrences of a string in a piece of text with another
+        # string
+        #
+        # @param value [String] Text to translate
+        # @param str_to_replace [String] String to be replaced
+        # @param replacement_str [String] Replacement text
+        # @return [String] Translated text
+        def self.translate(value, str_to_replace, replacement_str)
+          return value if value.nil? || value.empty?
+          return value unless value.include?(str_to_replace)
+
+          value.gsub(str_to_replace, replacement_str)
+        end
+
+        # Normalizes whitespace in a string by:
+        # - Converting tabs and newlines to spaces
+        # - Collapsing multiple spaces to single space
+        # - Trimming leading and trailing whitespace
+        #
+        # @param text [String] Text to normalize
+        # @return [String] Normalized text
+        def self.normalize_whitespace(text)
+          return "" if text.nil? || text.empty?
+
+          text.gsub(/[\t\n\r]+/, " ")
+            .gsub(/\s+/, " ")
+            .strip
+        end
+
+        # Splits a string by whitespace into an array
+        #
+        # @param text [String] Text to split
+        # @return [Array<String>] Array of tokens
+        def self.split_whitespace(text)
+          return [] if text.nil? || text.empty?
+
+          normalize_whitespace(text).split
+        end
+      end
+    end
+  end
+end

data/lib/xseed/models/element_declaration.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Xseed
+  module Models
+    # Represents an XSD element declaration
+    #
+    # This model captures all properties of an xs:element declaration including
+    # name, type, occurrence constraints, and documentation.
+    #
+    # @example Creating an element
+    #   element = ElementDeclaration.new(
+    #     name: "Person",
+    #     type: "PersonType",
+    #     min_occurs: 0,
+    #     max_occurs: "unbounded"
+    #   )
+    #
+    class ElementDeclaration < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :type, :string
+      attribute :min_occurs, :integer, default: -> { 1 }
+      attribute :max_occurs, :string, default: -> { "1" }
+      attribute :nillable, Lutaml::Model::Type::Boolean, default: -> { false }
+      attribute :abstract, Lutaml::Model::Type::Boolean, default: -> { false }
+      attribute :substitution_group, :string
+      attribute :documentation, :string
+      attribute :default_value, :string
+      attribute :fixed_value, :string
+
+      xml do
+        root "element"
+        namespace "http://www.w3.org/2001/XMLSchema", "xs"
+
+        map_attribute "name", to: :name
+        map_attribute "type", to: :type
+        map_attribute "minOccurs", to: :min_occurs
+        map_attribute "maxOccurs", to: :max_occurs
+        map_attribute "nillable", to: :nillable
+        map_attribute "abstract", to: :abstract
+        map_attribute "substitutionGroup", to: :substitution_group
+        map_attribute "default", to: :default_value
+        map_attribute "fixed", to: :fixed_value
+      end
+
+      yaml do
+        map "name", to: :name
+        map "type", to: :type
+        map "min_occurs", to: :min_occurs
+        map "max_occurs", to: :max_occurs
+        map "nillable", to: :nillable
+        map "abstract", to: :abstract
+        map "substitution_group", to: :substitution_group
+        map "documentation", to: :documentation
+        map "default_value", to: :default_value
+        map "fixed_value", to: :fixed_value
+      end
+
+      json do
+        map "name", to: :name
+        map "type", to: :type
+        map "minOccurs", to: :min_occurs
+        map "maxOccurs", to: :max_occurs
+        map "nillable", to: :nillable
+        map "abstract", to: :abstract
+        map "substitutionGroup", to: :substitution_group
+        map "documentation", to: :documentation
+        map "defaultValue", to: :default_value
+        map "fixedValue", to: :fixed_value
+      end
+
+      # Parse an element declaration from an XSD Nokogiri node
+      #
+      # @param node [Nokogiri::XML::Element] The xs:element node
+      # @return [ElementDeclaration] The parsed element declaration
+      def self.from_xsd_node(node)
+        new(
+          name: node["name"],
+          type: node["type"],
+          min_occurs: parse_occurs(node["minOccurs"], 1),
+          max_occurs: node["maxOccurs"] || "1",
+          nillable: parse_boolean(node["nillable"]),
+          abstract: parse_boolean(node["abstract"]),
+          substitution_group: node["substitutionGroup"],
+          default_value: node["default"],
+          fixed_value: node["fixed"],
+          documentation: extract_documentation(node),
+        )
+      end
+
+      # Check if the element is optional (minOccurs = 0)
+      #
+      # @return [Boolean] true if the element is optional
+      def optional?
+        min_occurs.zero?
+      end
+
+      # Check if the element is unbounded (maxOccurs = "unbounded")
+      #
+      # @return [Boolean] true if the element is unbounded
+      def unbounded?
+        max_occurs == "unbounded"
+      end
+
+      # Check if the element has documentation
+      #
+      # @return [Boolean] true if documentation is present
+      def documented?
+        !documentation.nil? && !documentation.empty?
+      end
+
+      # Get occurrence string representation
+      #
+      # @return [String] Occurrence representation like "[0..1]" or "[1..∞]"
+      def occurrence_string
+        return "" if min_occurs == 1 && max_occurs == "1"
+
+        max_display = max_occurs == "unbounded" ? "∞" : max_occurs
+        "[#{min_occurs}..#{max_display}]"
+      end
+
+      private_class_method def self.parse_occurs(value, default)
+        return default if value.nil? || value.empty?
+
+        value.to_i
+      end
+
+      private_class_method def self.parse_boolean(value)
+        value == "true"
+      end
+
+      private_class_method def self.extract_documentation(node)
+        doc_node = node.at_xpath(
+          "xs:annotation/xs:documentation",
+          "xs" => "http://www.w3.org/2001/XMLSchema",
+        )
+        return nil unless doc_node
+
+        doc_node.text.strip
+      end
+    end
+  end
+end

data/lib/xseed/parser/xsd_parser.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Xseed
+  module Parser
+    # XSD Parser for extracting schema components and metadata
+    #
+    # This class parses XML Schema Definition (XSD) files using Nokogiri
+    # and provides methods to access schema components such as elements,
+    # types, groups, and documentation.
+    #
+    # @example Parse an XSD file
+    #   parser = Xseed::Parser::XsdParser.new("schema.xsd")
+    #   elements = parser.elements
+    #   types = parser.types
+    #
+    class XsdParser
+      attr_reader :document, :schema, :target_namespace
+
+      XSD_NS = "http://www.w3.org/2001/XMLSchema"
+
+      # Initialize the parser with an XSD file path
+      #
+      # @param xsd_file_path [String] Path to the XSD file
+      # @raise [Errno::ENOENT] if file does not exist
+      def initialize(xsd_file_path)
+        content = File.read(xsd_file_path)
+        @document = Nokogiri::XML(content, &:strict)
+        @schema = @document.root
+
+        raise ParserError, "Invalid XSD: No root element found" unless @schema
+
+        parse_schema
+      rescue Nokogiri::XML::SyntaxError => e
+        raise ParserError, "Invalid XML syntax: #{e.message}"
+      end
+
+      # Get the elementFormDefault attribute value
+      #
+      # @return [String, nil] The elementFormDefault value
+      def element_form_default
+        schema["elementFormDefault"]
+      end
+
+      # Get the schema version attribute
+      #
+      # @return [String, nil] The schema version if present
+      def schema_version
+        schema["version"]
+      end
+
+      # Get all global element definitions
+      #
+      # @return [Array<Nokogiri::XML::Element>] Array of element nodes
+      def elements
+        xpath("//xs:schema/xs:element")
+      end
+
+      # Get all complex type definitions
+      #
+      # @return [Array<Nokogiri::XML::Element>] Array of complexType nodes
+      def complex_types
+        xpath("//xs:schema/xs:complexType")
+      end
+
+      # Get all simple type definitions
+      #
+      # @return [Array<Nokogiri::XML::Element>] Array of simpleType nodes
+      def simple_types
+        xpath("//xs:schema/xs:simpleType")
+      end
+
+      # Get all type definitions (both complex and simple)
+      #
+      # @return [Array<Nokogiri::XML::Element>] Array of type nodes
+      def types
+        complex_types + simple_types
+      end
+
+      # Get all group definitions
+      #
+      # @return [Array<Nokogiri::XML::Element>] Array of group nodes
+      def groups
+        xpath("//xs:schema/xs:group")
+      end
+
+      # Get all attribute group definitions
+      #
+      # @return [Array<Nokogiri::XML::Element>] Array of attributeGroup nodes
+      def attribute_groups
+        xpath("//xs:schema/xs:attributeGroup")
+      end
+
+      # Get namespace mappings from the schema
+      #
+      # @return [Hash<String, String>] Hash mapping prefixes to namespace URIs
+      def namespaces
+        schema.namespaces.transform_keys do |key|
+          key.sub(/^xmlns:/, "")
+        end
+      end
+
+      # Get schema-level documentation
+      #
+      # @return [String, nil] The documentation text or nil
+      def documentation
+        doc_node = schema.at_xpath(
+          "xs:annotation/xs:documentation",
+          "xs" => XSD_NS,
+        )
+        return nil unless doc_node
+
+        doc_node.text.strip
+      end
+
+      # Get documentation for a specific element by name
+      #
+      # @param element_name [String] The name of the element
+      # @return [String, nil] The documentation text or nil
+      def element_documentation(element_name)
+        element = schema.at_xpath(
+          "xs:element[@name='#{element_name}']",
+          "xs" => XSD_NS,
+        )
+        return nil unless element
+
+        extract_documentation(element)
+      end
+
+      # Get documentation for a specific type by name
+      #
+      # @param type_name [String] The name of the type
+      # @return [String, nil] The documentation text or nil
+      def type_documentation(type_name)
+        type_node = schema.at_xpath(
+          "xs:complexType[@name='#{type_name}'] | " \
+          "xs:simpleType[@name='#{type_name}']",
+          "xs" => XSD_NS,
+        )
+        return nil unless type_node
+
+        extract_documentation(type_node)
+      end
+
+      # Get all import declarations
+      #
+      # @return [Array<Nokogiri::XML::Element>] Array of import nodes
+      def imports
+        xpath("//xs:schema/xs:import")
+      end
+
+      # Get all include declarations
+      #
+      # @return [Array<Nokogiri::XML::Element>] Array of include nodes
+      def includes
+        xpath("//xs:schema/xs:include")
+      end
+
+      private
+
+      # Parse the schema and extract metadata
+      def parse_schema
+        return unless schema
+
+        @target_namespace = schema["targetNamespace"]
+      end
+
+      # Execute XPath query with XSD namespace
+      #
+      # @param xpath_expr [String] XPath expression
+      # @return [Array<Nokogiri::XML::Element>] Matching nodes
+      def xpath(xpath_expr)
+        document.xpath(xpath_expr, "xs" => XSD_NS)
+      end
+
+      # Extract documentation from an XML node
+      #
+      # @param node [Nokogiri::XML::Element] The node to extract from
+      # @return [String, nil] The documentation text or nil
+      def extract_documentation(node)
+        doc_node = node.at_xpath(
+          "xs:annotation/xs:documentation",
+          "xs" => XSD_NS,
+        )
+        return nil unless doc_node
+
+        doc_node.text.strip
+      end
+    end
+  end
+end

data/lib/xseed/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Xseed
+  VERSION = "1.0.0"
+end

data/lib/xseed.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "xseed/version"
+
+module Xseed
+  class Error < StandardError; end
+  class ParserError < Error; end
+  class GenerationError < Error; end
+
+  autoload :CLI, "xseed/cli"
+
+  module Parser
+    autoload :XsdParser, "xseed/parser/xsd_parser"
+    autoload :SchemaParser, "xseed/parser/schema_parser"
+    autoload :NamespaceResolver, "xseed/parser/namespace_resolver"
+    autoload :AnnotationExtractor, "xseed/parser/annotation_extractor"
+  end
+
+  module Models
+    autoload :Schema, "xseed/models/schema"
+    autoload :Element, "xseed/models/element"
+    autoload :ComplexType, "xseed/models/complex_type"
+    autoload :SimpleType, "xseed/models/simple_type"
+    autoload :Attribute, "xseed/models/attribute"
+    autoload :Group, "xseed/models/group"
+  end
+
+  module Documentation
+    autoload :Generator, "xseed/documentation/generator"
+    autoload :HtmlGenerator, "xseed/documentation/html_generator"
+    autoload :Config, "xseed/documentation/config"
+
+    module Core
+      autoload :Parameters, "xseed/documentation/core/parameters"
+      autoload :Constants, "xseed/documentation/core/constants"
+    end
+
+    module Utilities
+      autoload :StringHelpers, "xseed/documentation/utilities/string_helpers"
+      autoload :NamespaceHelpers,
+               "xseed/documentation/utilities/namespace_helpers"
+      autoload :ReferenceResolver,
+               "xseed/documentation/utilities/reference_resolver"
+      autoload :SchemaLocationHelper,
+               "xseed/documentation/utilities/schema_location_helper"
+    end
+
+    module Renderers
+      autoload :XMLPrettyPrinter,
+               "xseed/documentation/renderers/xml_pretty_printer"
+      autoload :GlossaryRenderer,
+               "xseed/documentation/renderers/glossary_renderer"
+      autoload :UIComponentRenderer,
+               "xseed/documentation/renderers/ui_component_renderer"
+    end
+
+    module Sections
+      autoload :ComponentLinks,
+               "xseed/documentation/sections/component_links"
+      autoload :HierarchyTables,
+               "xseed/documentation/sections/hierarchy_tables"
+      autoload :PropertiesTables,
+               "xseed/documentation/sections/properties_tables"
+      autoload :SchemaComponents,
+               "xseed/documentation/sections/schema_components"
+    end
+
+    module Presentation
+      autoload :HTMLDocument,
+               "xseed/documentation/presentation/html_document"
+      autoload :Navigation, "xseed/documentation/presentation/navigation"
+      autoload :CSSStyles, "xseed/documentation/presentation/css_styles"
+      autoload :JavaScript, "xseed/documentation/presentation/javascript"
+    end
+  end
+end

data/xseed.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/xseed/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "xseed"
+  spec.version       = Xseed::VERSION
+  spec.authors       = ["Ribose"]
+  spec.email         = ["open.source@ribose.com"]
+
+  spec.summary       = "Ruby XSD documentation generator with unified SVG and HTML output"
+  spec.description   = "Generate comprehensive XSD documentation with SVG diagrams (via xsdvi gem) and HTML reference (XS3P port)"
+  spec.homepage      = "https://github.com/metanorma/xseed"
+  spec.license       = "BSD-2-Clause"
+
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.adoc"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:test|spec|features)/})
+    end
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "lutaml-model", "~> 0.7"
+  spec.add_dependency "lutaml-xsd", "~> 1.0"
+  spec.add_dependency "nokogiri", "~> 1.16"
+  spec.add_dependency "thor", "~> 1.3"
+  spec.add_dependency "xsdvi", "~> 1.0"
+end