scjson 0.3.3 → 0.4.0

data/lib/scjson/version.rb

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

data/lib/scjson.rb

@@ -7,13 +7,22 @@
 # Licensed under the BSD 1-Clause License.
 
 require 'json'
-require 'nokogiri'
+begin
+  require 'nokogiri'
+  NOKOGIRI_AVAILABLE = true
+rescue LoadError
+  NOKOGIRI_AVAILABLE = false
+end
+require 'shellwords'
 
 require_relative 'scjson/version'
+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',
@@ -30,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
@@ -45,14 +56,42 @@ module Scjson
   # @param [Boolean] omit_empty Remove empty containers when true.
   # @return [String] Canonical scjson output.
   def xml_to_json(xml_str, omit_empty = true)
-    doc = Nokogiri::XML(xml_str) { |cfg| cfg.strict.nonet }
-    root = locate_root(doc)
-    raise ArgumentError, 'Document missing <scxml> root element' unless root
-
-    map = element_to_hash(root)
-    collapse_whitespace(map)
-    remove_empty(map) if omit_empty
-    JSON.pretty_generate(map)
+    if NOKOGIRI_AVAILABLE
+      doc = Nokogiri::XML(xml_str) { |cfg| cfg.strict.nonet }
+      root = locate_root(doc)
+      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)
+    end
+    # Fallback: use Python CLI converter when Nokogiri is unavailable.
+    begin
+      require 'tmpdir'
+      Dir.mktmpdir('scjson-rb-xml2json') do |dir|
+        in_path = File.join(dir, 'in.scxml')
+        out_path = File.join(dir, 'out.scjson')
+        File.write(in_path, xml_str)
+        py_candidates = [ENV['PYTHON'], 'python3', 'python'].compact.uniq
+        ok = false
+        py_candidates.each do |py|
+          # Try package entrypoint; add repo-local 'py' to PYTHONPATH for import
+          repo_py = File.expand_path('../../py', __dir__)
+          env = {}
+          current_pp = ENV['PYTHONPATH']
+          env['PYTHONPATH'] = current_pp ? (repo_py + File::PATH_SEPARATOR + current_pp) : repo_py
+          cmd = [py, '-m', 'scjson.cli', 'json', in_path, '-o', out_path]
+          ok = system(env, *cmd, out: File::NULL, err: File::NULL) && File.file?(out_path)
+          break if ok
+        end
+        raise 'python converter failed' unless ok
+        return File.read(out_path)
+      end
+    rescue StandardError => e
+      raise LoadError, "SCXML->JSON conversion unavailable: Nokogiri missing and external converter failed (#{e})"
+    end
   end
 
   ##
@@ -61,13 +100,40 @@ module Scjson
   # @param [String] json_str Canonical scjson input.
   # @return [String] XML document encoded as UTF-8.
   def json_to_xml(json_str)
-    data = JSON.parse(json_str)
-    remove_empty(data)
-    doc = Nokogiri::XML::Document.new
-    doc.encoding = 'utf-8'
-    root = build_element(doc, 'scxml', data)
-    doc.root = root
-    doc.to_xml
+    if NOKOGIRI_AVAILABLE
+      data = JSON.parse(json_str)
+      remove_empty(data)
+      doc = Nokogiri::XML::Document.new
+      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.
+    begin
+      require 'tmpdir'
+      Dir.mktmpdir('scjson-rb-json2xml') do |dir|
+        in_path = File.join(dir, 'in.scjson')
+        out_path = File.join(dir, 'out.scxml')
+        File.write(in_path, json_str)
+        py_candidates = [ENV['PYTHON'], 'python3', 'python'].compact.uniq
+        ok = false
+        py_candidates.each do |py|
+          repo_py = File.expand_path('../../py', __dir__)
+          env = {}
+          current_pp = ENV['PYTHONPATH']
+          env['PYTHONPATH'] = current_pp ? (repo_py + File::PATH_SEPARATOR + current_pp) : repo_py
+          cmd = [py, '-m', 'scjson.cli', 'xml', in_path, '-o', out_path]
+          ok = system(env, *cmd, out: File::NULL, err: File::NULL) && File.file?(out_path)
+          break if ok
+        end
+        raise 'python converter failed' unless ok
+        return File.read(out_path)
+      end
+    rescue StandardError => e
+      raise LoadError, "JSON->SCXML conversion unavailable: Nokogiri missing and external converter failed (#{e})"
+    end
   end
 
   # ----------------------------
@@ -84,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]
@@ -104,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?
@@ -123,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)
@@ -179,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'
@@ -203,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'
@@ -318,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'
@@ -330,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)
@@ -375,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
@@ -391,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
@@ -425,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)
@@ -452,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
 
@@ -468,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.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Softoboros Technology Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-01 00:00:00.000000000 Z
+date: 2026-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -24,7 +24,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
+description: 'scjson: SCXML ↔ JSON converter, validator, and execution trace interface.
+  Provides CLI tools for conversion, validation, and emitting deterministic traces
+  compatible with SCION semantics.'
 email:
 - info@softoboros.com
 executables:
@@ -32,14 +34,25 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- LEGAL.md
+- LICENSE
+- README.md
 - bin/scjson
 - lib/scjson.rb
 - lib/scjson/cli.rb
+- lib/scjson/engine.rb
+- lib/scjson/engine/context.rb
+- lib/scjson/types.rb
 - lib/scjson/version.rb
-homepage:
+homepage: https://github.com/SoftOboros/scjson
 licenses:
 - BSD-1-Clause
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/SoftOboros/scjson
+  documentation_uri: https://github.com/SoftOboros/scjson/tree/main/docs
+  changelog_uri: https://github.com/SoftOboros/scjson/releases
+  homepage_uri: https://github.com/SoftOboros/scjson
+  keywords: scxml,statecharts,state-machine,scjson,scml,execution
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -58,5 +71,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: SCXML <-> scjson converter and validator
+summary: SCXML/SCML execution, SCXML <-> scjson converter and validator
 test_files: []