scjson 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a958225a6d29fbafd51d046f9c38d7c65ff98aa80c7727e321c6c68ac952c00a
-  data.tar.gz: 13acb52ec061e0ab3c0c09c76a9ea172370938e6770efa7ee69a162183365fe9
+  metadata.gz: cf4ac84d8fbd3c14f1f60e0e4b36bb543b9d0c0bbf018d7dcd21c070a2503553
+  data.tar.gz: 1ed8ff218919ff5709709c8f880f13cdec73a622a3890ac5e305a296aa7fe806
 SHA512:
-  metadata.gz: b958161b70d561ccfdc324b1855a5f1a710edb0506798764c83e9dc8d26ef2989e2d8c1953a4a05834a01872b2b832adfde4d3a000e8e05f71b13f5c02a6e8a2
-  data.tar.gz: 5991fbfe49a89974bedf45a8030cdf5fead46e001fd3851ca14ac5f1131a8519ba3f16d487499a839d7a97c208e0652de82b6ffb7a48c439ab2cdb753f5e9188
+  metadata.gz: 1fad325a32b3b769dac3be62beab1e6013d60e1f6b5690aeea076c74f6446547e0caa4474780c5c04694837b120833b48dc236addf53454a84e7377070fae8e0
+  data.tar.gz: 01acafaa1b2ee89da044ee309efb93becddb66abea2f3f52bda40e9970807586a42d91498b30edb1b51bceb2908c9d191b6330acf3355d2e60f2d7eca2a0e55e

data/lib/scjson/version.rb

@@ -7,5 +7,5 @@
 # Licensed under the BSD 1-Clause License.
 
 module Scjson
-  VERSION = '0.3.5'
+  VERSION = '0.4.0'
 end

data/lib/scjson.rb

@@ -21,6 +21,8 @@ require_relative 'scjson/types'
 # Canonical SCXML <-> scjson conversion for the Ruby agent.
 module Scjson
   XMLNS = 'http://www.w3.org/2005/07/scxml'.freeze
+  XINCLUDE_NS = 'http://www.w3.org/2001/XInclude'.freeze
+  XINCLUDE_CLARK_INCLUDE = "{#{XINCLUDE_NS}}include".freeze
 
   ATTRIBUTE_MAP = {
     'datamodel' => 'datamodel_attribute',
@@ -37,6 +39,8 @@ module Scjson
     else content donedata initial
   ].freeze
 
+  SOURCE_BODY_TAGS = %w[script data].freeze
+
   STRUCTURAL_FIELDS = %w[
     state parallel final history transition invoke finalize datamodel data
     onentry onexit log send cancel raise assign script foreach param if_value
@@ -58,6 +62,7 @@ module Scjson
       raise ArgumentError, 'Document missing <scxml> root element' unless root
 
       map = element_to_hash(root)
+      attach_root_sibling_comments(doc, root, map)
       collapse_whitespace(map)
       remove_empty(map) if omit_empty
       return JSON.pretty_generate(map)
@@ -102,6 +107,7 @@ module Scjson
       doc.encoding = 'utf-8'
       root = build_element(doc, 'scxml', data)
       doc.root = root
+      add_preceding_help_text_comments(doc, root, data)
       return doc.to_xml
     end
     # Fallback: use Python CLI converter when Nokogiri is unavailable.
@@ -144,6 +150,36 @@ module Scjson
   end
   private_class_method :local_name
 
+  def scxml_element?(node)
+    ns = node.namespace&.href
+    SCXML_ELEMENTS.include?(local_name(node)) && (ns.nil? || ns.empty? || ns == XMLNS)
+  end
+  private_class_method :scxml_element?
+
+  def extension_element?(node)
+    ns = node.namespace&.href
+    !ns.nil? && !ns.empty? && ns != XMLNS
+  end
+  private_class_method :extension_element?
+
+  def comment_node?(node)
+    node.respond_to?(:comment?) && node.comment?
+  end
+  private_class_method :comment_node?
+
+  def processing_instruction_node?(node)
+    node.respond_to?(:processing_instruction?) && node.processing_instruction?
+  end
+  private_class_method :processing_instruction_node?
+
+  def clark_name(node)
+    ns = node.namespace&.href
+    return node.name if ns.nil? || ns.empty?
+
+    "{#{ns}}#{local_name(node)}"
+  end
+  private_class_method :clark_name
+
   def append_child(hash, key, value)
     if hash.key?(key)
       existing = hash[key]
@@ -164,8 +200,81 @@ module Scjson
   end
   private_class_method :wrap_list
 
+  def repair_comment_text(raw)
+    text = raw.to_s
+    return text.strip unless text.include?("\n")
+
+    lines = text.lines.map { |line| line.chomp("\n") }
+    lines.shift while !lines.empty? && lines.first.strip.empty?
+    lines.pop while !lines.empty? && lines.last.strip.empty?
+    return '' if lines.empty?
+
+    indents = lines.map do |line|
+      next if line.strip.empty?
+
+      line.length - line.sub(/\A[ \t]+/, '').length
+    end.compact
+    common = indents.empty? ? 0 : indents.min
+    lines = lines.map { |line| line.length >= common ? line[common, line.length] : line } if common.positive?
+    lines.join("\n")
+  end
+  private_class_method :repair_comment_text
+
+  def emit_safe_comment_text(text)
+    safe = text.to_s.gsub('--', '- -')
+    safe = "#{safe} " if safe.end_with?('-')
+    safe
+  end
+  private_class_method :emit_safe_comment_text
+
+  def append_help_text(map, comments, prepend: false)
+    repaired = comments.map(&:to_s)
+    return if repaired.empty?
+
+    existing = map['help_text']
+    if existing
+      existing = wrap_list(existing)
+      map['help_text'] = prepend ? repaired + existing : existing + repaired
+    else
+      map['help_text'] = repaired
+    end
+  end
+  private_class_method :append_help_text
+
+  def add_preceding_help_text_comments(doc, element, map)
+    return unless map.is_a?(Hash)
+
+    wrap_list(map['help_text']).each do |text|
+      element.add_previous_sibling(Nokogiri::XML::Comment.new(doc, emit_safe_comment_text(text)))
+    end
+  end
+  private_class_method :add_preceding_help_text_comments
+
+  def add_child_element(doc, parent, child_name, child_map)
+    child = build_element(doc, child_name, child_map)
+    if child_map.is_a?(Hash)
+      wrap_list(child_map['help_text']).each do |text|
+        parent.add_child(Nokogiri::XML::Comment.new(doc, emit_safe_comment_text(text)))
+      end
+    end
+    parent.add_child(child)
+  end
+  private_class_method :add_child_element
+
+  def attach_root_sibling_comments(doc, root, map)
+    comments = []
+    doc.children.each do |child|
+      next if child.equal?(root)
+      next unless comment_node?(child)
+
+      comments << repair_comment_text(child.text || '')
+    end
+    append_help_text(map, comments) unless comments.empty?
+  end
+  private_class_method :attach_root_sibling_comments
+
   def any_element_to_hash(node)
-    result = { 'qname' => node.name }
+    result = { 'qname' => clark_name(node) }
     text = node.text
     result['text'] = text.to_s if text
     unless node.attribute_nodes.empty?
@@ -183,9 +292,11 @@ module Scjson
   end
   private_class_method :any_element_to_hash
 
-  def element_to_hash(node)
+  def element_to_hash(node, inside_source_body = false, inside_extension = false)
     map = {}
     local = local_name(node)
+    elem_in_source = inside_source_body || SOURCE_BODY_TAGS.include?(local)
+    elem_in_extension = inside_extension || (!SCXML_ELEMENTS.include?(local) && local != 'scxml')
 
     node.attribute_nodes.each do |attr|
       name = local_name(attr)
@@ -239,17 +350,32 @@ module Scjson
     end
 
     text_items = []
+    pending_comments = []
     node.children.each do |child|
-      if child.element?
+      if comment_node?(child)
+        pending_comments << repair_comment_text(child.text || '')
+      elsif processing_instruction_node?(child)
+        next
+      elsif child.element?
         child_local = local_name(child)
-        if SCXML_ELEMENTS.include?(child_local)
+        if scxml_element?(child)
           key = case child_local
                 when 'if' then 'if_value'
                 when 'else' then 'else_value'
                 when 'raise' then 'raise_value'
                 else child_local
                 end
-          child_map = element_to_hash(child)
+          child_map = element_to_hash(child, elem_in_source || local == 'content', elem_in_extension)
+          target_eligible = SCXML_ELEMENTS.include?(child_local) && !elem_in_source && !elem_in_extension
+          if !pending_comments.empty? && local == 'content' && child_local == 'scxml'
+            # Comments inside an inline <content> payload are payload-local,
+            # not authoring metadata for the nested machine.
+          elsif !pending_comments.empty? && target_eligible
+            append_help_text(child_map, pending_comments, prepend: true)
+          elsif !pending_comments.empty? && SCXML_ELEMENTS.include?(local) && !elem_in_source && !elem_in_extension
+            append_help_text(map, pending_comments)
+          end
+          pending_comments = []
           target_key = if child_local == 'scxml' && local != 'scxml'
                          'content'
                        elsif local == 'content' && child_local == 'scxml'
@@ -263,14 +389,27 @@ module Scjson
             append_child(map, target_key, child_map)
           end
         else
-          append_child(map, 'content', any_element_to_hash(child))
+          if !pending_comments.empty? && SCXML_ELEMENTS.include?(local) && !elem_in_source && !elem_in_extension
+            append_help_text(map, pending_comments)
+          end
+          pending_comments = []
+          target_key = extension_element?(child) ? 'other_element' : 'content'
+          append_child(map, target_key, any_element_to_hash(child))
         end
       elsif child.text?
         value = child.text
+        if value && !value.strip.empty? && !pending_comments.empty?
+          append_help_text(map, pending_comments) if SCXML_ELEMENTS.include?(local) && !elem_in_source && !elem_in_extension
+          pending_comments = []
+        end
         text_items << value if value && !value.strip.empty?
       end
     end
 
+    if !pending_comments.empty? && SCXML_ELEMENTS.include?(local) && !elem_in_source && !elem_in_extension
+      append_help_text(map, pending_comments)
+    end
+
     text_items.each { |text| append_child(map, 'content', text) }
 
     if local == 'scxml'
@@ -378,6 +517,11 @@ module Scjson
     raise ArgumentError, 'Expected object for element construction' unless map.is_a?(Hash)
 
     element_name = map['qname'] || name
+    attrs = map['attributes'].is_a?(Hash) ? map['attributes'].dup : {}
+    if element_name == XINCLUDE_CLARK_INCLUDE
+      element_name = 'xi:include'
+      attrs['xmlns:xi'] ||= XINCLUDE_NS
+    end
     element = Nokogiri::XML::Element.new(element_name, doc)
 
     if name == 'scxml'
@@ -390,23 +534,28 @@ module Scjson
       element.add_child(Nokogiri::XML::Text.new(map['text'], doc))
     end
 
-    if map['attributes'].is_a?(Hash)
-      map['attributes'].each do |attr_name, attr_value|
-        element[attr_name] = attr_value if attr_value
-      end
+    attrs.each do |attr_name, attr_value|
+      element[attr_name] = attr_value if attr_value
     end
 
     map.each do |key, value|
-      next if %w[qname text attributes].include?(key)
+      next if %w[qname text attributes help_text].include?(key)
 
       case key
       when 'content'
         handle_content_nodes(doc, element, value, element_name)
+      when 'other_element'
+        wrap_list(value).each do |child_map|
+          next unless child_map.is_a?(Hash)
+
+          child_name = child_map['qname'] || 'content'
+          add_child_element(doc, element, child_name, child_map)
+        end
       when 'children'
         wrap_list(value).each do |child_map|
           next unless child_map.is_a?(Hash)
           child_name = child_map['qname'] || 'content'
-          element.add_child(build_element(doc, child_name, child_map))
+          add_child_element(doc, element, child_name, child_map)
         end
       when 'other_attributes'
         next unless value.is_a?(Hash)
@@ -435,7 +584,7 @@ module Scjson
           element['initial'] = joined
         else
           wrap_list(value).each do |child|
-            element.add_child(build_element(doc, 'initial', child))
+            add_child_element(doc, element, 'initial', child)
           end
           next
         end
@@ -451,12 +600,12 @@ module Scjson
 
         if STRUCTURAL_FIELDS.include?(key) || %w[if_value else_value raise_value].include?(key)
           wrap_list(value).each do |child|
-            element.add_child(build_element(doc, child_name, child))
+            add_child_element(doc, element, child_name, child)
           end
         elsif value.is_a?(Array) && value.all? { |item| !item.is_a?(Hash) }
           element[key] = join_tokens(value)
         elsif value.is_a?(Hash)
-          element.add_child(build_element(doc, child_name, value))
+          add_child_element(doc, element, child_name, value)
         elsif !value.nil?
           element[key] = value.to_s
         end
@@ -485,26 +634,32 @@ module Scjson
 
       next unless item.is_a?(Hash)
 
-      if parent_name == 'send' && item.keys == ['content']
+      if parent_name == 'send' && (item.keys - ['help_text']) == ['content']
+        wrap_list(item['help_text']).each do |text|
+          element.add_child(Nokogiri::XML::Comment.new(doc, emit_safe_comment_text(text)))
+        end
         wrap_list(item['content']).each do |inner|
           content_element = Nokogiri::XML::Element.new('content', doc)
           if inner.is_a?(String)
             content_element.add_child(Nokogiri::XML::Text.new(inner, doc))
           elsif inner.is_a?(Hash)
-            content_element.add_child(build_element(doc, 'content', inner))
+            add_child_element(doc, content_element, 'content', inner)
           end
           element.add_child(content_element)
         end
         next
       end
 
-      if parent_name == 'donedata' && item.keys == ['content']
+      if parent_name == 'donedata' && (item.keys - ['help_text']) == ['content']
+        wrap_list(item['help_text']).each do |text|
+          element.add_child(Nokogiri::XML::Comment.new(doc, emit_safe_comment_text(text)))
+        end
         content_element = Nokogiri::XML::Element.new('content', doc)
         wrap_list(item['content']).each do |inner|
           if inner.is_a?(String)
             content_element.add_child(Nokogiri::XML::Text.new(inner, doc))
           elsif inner.is_a?(Hash)
-            content_element.add_child(build_element(doc, 'content', inner))
+            add_child_element(doc, content_element, 'content', inner)
           end
         end
         element.add_child(content_element)
@@ -512,8 +667,7 @@ module Scjson
       end
 
       if item.key?('qname')
-        child = build_element(doc, item['qname'], item)
-        element.add_child(child)
+        add_child_element(doc, element, item['qname'], item)
         next
       end
 
@@ -528,8 +682,7 @@ module Scjson
       if parent_name == 'data' && child_name == 'content'
         element.add_child(Nokogiri::XML::Text.new(item['content'].to_s, doc))
       else
-        child_element = build_element(doc, child_name, item)
-        element.add_child(child_element)
+        add_child_element(doc, element, child_name, item)
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scjson
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.4.0
 platform: ruby
 authors:
 - Softoboros Technology Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-04 00:00:00.000000000 Z
+date: 2026-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri