interscript 2.4.5 → 3.0.0

data/lib/interscript/isc/document_builder.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+module Interscript
+  module Isc
+    # Builds an intermediate "document hash" from a raw parslet tree.
+    # The hash shape is intentionally simple so it can be:
+    #   - inspected in tests
+    #   - serialized to JSON IR for cross-runtime conformance
+    #   - consumed by interscript-ruby's existing Node::Document builder
+    #
+    # This is the bridge between the parser and the runtime. It does no
+    # semantic validation beyond shape; that lives in the runtime layer.
+    class DocumentBuilder
+      SCHEMA_VERSION = 1
+
+      # Metadata fields that the Ruby DSL stores as Arrays (STANDARD_ARRAY_KEYS).
+      # ISC stores them as generic fields, so we wrap in an Array to match.
+      ARRAY_METADATA_FIELDS = %i[notes implementation_notes original_notes url].freeze
+
+      def self.build(tree, filename: nil)
+        new(tree, filename: filename).build
+      end
+
+      def initialize(tree, filename: nil)
+        @tree = tree
+        @filename = filename
+        @transform = Transform.new
+      end
+
+      def build
+        node = @tree[:system] || @tree
+        code = unquote(node[:system_code])
+
+        body = Array(node[:body])
+        metadata_hash = {}
+        aliases_arr = []
+        tests_arr = []
+        stages_arr = []
+        dependencies_arr = []
+
+        body.each do |item|
+          if item[:metadata]
+            metadata_hash.merge!(extract_metadata(item[:metadata]))
+          elsif item[:aliases]
+            aliases_arr.concat(extract_aliases(item[:aliases]))
+          elsif item[:tests]
+            tests_arr.concat(extract_tests(item[:tests]))
+          elsif item[:stage]
+            stages_arr << extract_stage(item)
+          elsif item[:target]
+            dependencies_arr << extract_dependency(item)
+          end
+        end
+
+        {
+          schemaVersion: SCHEMA_VERSION,
+          filename: @filename,
+          systemCode: code,
+          urn: derive_urn(code),
+          metadata: metadata_hash,
+          aliases: aliases_arr,
+          tests: tests_arr,
+          stages: stages_arr,
+          dependencies: dependencies_arr
+        }
+      end
+
+      private
+
+      # Apply Transform to a quoted_string fragment and read back the string value.
+      def unquote(fragment)
+        return "" if fragment.nil?
+        return fragment.to_s unless fragment.is_a?(Hash)
+        # Direct decode for the overwhelmingly common shape — routing
+        # every quoted string through Transform pattern matching
+        # dominated large-map builds.
+        return Transform.decode_string_parts(fragment[:string]) if fragment.key?(:string)
+
+        fragment.to_s
+      end
+
+      def unescape_braces(text)
+        text.gsub(/\\([{}\\])/, '\1')
+      end
+
+      def parse_array_field(val)
+        return [] if val.nil? || val.to_s.strip.empty?
+        text = val.to_s
+        return [text.strip] unless text.include?("\n-")
+        # Multi-line YAML list: merge continuation lines preserving paragraph breaks
+        items = []
+        text.lines.each do |l|
+          stripped = l.strip
+          if stripped.start_with?("- ")
+            items << stripped[2..]
+          elsif stripped.empty? && items.any?
+            items[-1] = (items[-1] || "") + "\n\n"
+          elsif !stripped.empty? && items.any?
+            items[-1] = (items[-1] || "") + "\n" + stripped
+          end
+        end
+        items = items.empty? ? [text.strip] : items
+        # Treat single-item [""] arrays (YAML empty list markers) as empty arrays
+        (items == [""]) ? [] : items
+      end
+
+      def normalize_heredoc(text)
+        lines = text.lines.map(&:chomp)
+        content_lines = lines.reject { |l| l.strip.empty? }
+        return "" if content_lines.empty?
+        return content_lines.first.strip if content_lines.size == 1
+
+        # YAML-style dedent: strip the minimum indent across all non-blank
+        # lines. The first line's indent may have been partially consumed
+        # by the grammar, so we compute min_indent from lines 2+ and treat
+        # the first line as having at least that much indent.
+        min_indent = content_lines
+          .drop(1)
+          .map { |l| l[/\A[ \t]*/].length }
+          .min || 0
+
+        lines.map do |l|
+          if l.strip.empty?
+            ""
+          elsif l[/\A[ \t]*/].length >= min_indent
+            l[min_indent..]
+          else
+            l.strip
+          end
+        end.join("\n").rstrip.then { |s| (text.end_with?("\n") && !text.end_with?("\n\n")) ? s + "\n" : s }
+      end
+
+      # Apply Transform to an identifier fragment.
+      def ident(fragment)
+        return "" if fragment.nil?
+        return fragment.to_s unless fragment.is_a?(Hash)
+        return fragment.to_s unless fragment.key?(:identifier)
+
+        @transform.apply(fragment).to_s
+      end
+
+      # Extract `name: "value"` pairs from a parslet kwarg tree into a
+      # string-keyed Hash. The tree is `{kwarg: [{kwarg_name:, kwarg_value:}, ...]}`
+      # or a single `{kwarg_name:, kwarg_value:}` for one kwarg.
+      def extract_kwargs(fragment)
+        return {} if fragment.nil?
+        raw = fragment.is_a?(Hash) ? fragment[:kwarg] : fragment
+        kwargs = case raw
+        when Hash then [raw]
+        when Array then raw.select { |k| k.is_a?(Hash) }
+        else []
+        end
+        kwargs.each_with_object({}) do |kw, h|
+          next unless kw.is_a?(Hash)
+          h[ident(kw[:kwarg_name])] = unquote(kw[:kwarg_value])
+        end
+      end
+
+      def derive_urn(code)
+        "urn:iso:24229:system:#{code.downcase}"
+      end
+
+      def extract_metadata(arr)
+        h = {}
+        Array(arr).each do |field|
+          if field.key?(:specification)
+            h[:specification] ||= []
+            h[:specification] << unquote(field[:specification])
+          elsif field.key?(:notes)
+            h[:notes] ||= []
+            Array(field[:notes]).each do |n|
+              note_val = n.is_a?(Hash) ? n[:note] : n
+              h[:notes] << normalize_heredoc(unquote(note_val).to_s)
+            end
+          elsif field.key?(:note)
+            h[:notes] ||= []
+            h[:notes] << normalize_heredoc(unquote(field[:note]).to_s)
+          elsif field.key?(:provenance)
+            h[:provenance] ||= []
+            h[:provenance] << unquote(field[:provenance])
+          elsif field.key?(:relations)
+            h[:relations] = extract_relations(field[:relations])
+          elsif field.key?(:description)
+            desc = field[:description]
+            desc_str = desc.is_a?(Array) ? desc.join : desc.to_s
+            h[:description] = normalize_heredoc(unescape_braces(desc_str)) + "\n"
+          elsif field.key?(:field_name)
+            # Generic field: identifier + raw value
+            name = ident(field[:field_name]).to_sym
+            if field.key?(:field_block)
+              val = normalize_heredoc(unescape_braces(field[:field_block].to_s))
+            else
+              raw = field[:field_value]
+              val = case raw
+              when Hash
+                raw.key?(:string) ? unquote(raw) : (raw[:raw]&.to_s || "").strip
+              when nil then ""
+              else raw.to_s.strip
+              end
+            end
+            # DSL stores these as Arrays — match that convention.
+            h[name] = if ARRAY_METADATA_FIELDS.include?(name)
+              parse_array_field(val)
+            else
+              val
+            end
+          else
+            # Specific named field (authority, name, system_status, etc.)
+            field.each do |key, val|
+              next if val.nil?
+              h[key] = (val.is_a?(Hash) && val.key?(:string)) ? unquote(val) : val.to_s
+            end
+          end
+        end
+        h
+      end
+
+      def extract_relations(arr)
+        Array(arr).map do |r|
+          {
+            type: r[:type].to_s,
+            system: unquote(r[:system]),
+            note: r[:note] && unquote(r[:note])
+          }.compact
+        end
+      end
+
+      def extract_aliases(arr)
+        Array(arr).map do |a|
+          {name: ident(a[:name]), value: materialize(a[:value])}
+        end
+      end
+
+      def extract_tests(arr)
+        Array(arr).map do |t|
+          next {input: "", expected: ""} unless t.is_a?(Hash)
+
+          input_val = t[:input]
+          expected_val = t[:expected]
+          note_val = t[:note]
+
+          {
+            input: input_val.is_a?(Hash) ? unquote(input_val) : input_val.to_s,
+            expected: expected_val.is_a?(Hash) ? unquote(expected_val) : expected_val.to_s,
+            note: note_val.is_a?(Hash) ? unquote(note_val) : note_val&.to_s
+          }.compact
+        end
+      end
+
+      def extract_stage(item)
+        node = item[:stage]
+        name = ident(item[:stage_name])
+        body = Array(node).flat_map { |n| extract_stage_items(n) }
+        {name: name, body: body}
+      end
+
+      def extract_stage_items(n)
+        return [] unless n.is_a?(Hash)
+        if n[:sequence]
+          [{kind: :sequence, rules: filter_noop(Array(n[:sequence]).map { |r| extract_rule(r) })}]
+        elsif n[:parallel]
+          [{kind: :parallel, rules: filter_noop(Array(n[:parallel]).map { |r| extract_rule(r) })}]
+        elsif n[:separate]
+          [{kind: :separate, separator: n[:separator] ? materialize(n[:separator]) : nil}]
+        elsif n[:compose]
+          # The grammar captures both `compose` and `decompose` under this
+          # key — the value decides the directive. Dropping it compiled
+          # every decompose as NFC compose.
+          [{kind: n[:compose].to_s.to_sym}]
+        elsif n[:case]
+          item = {kind: :string_case, op: n[:case].to_s}
+          item[:kwargs] = extract_kwargs(n[:case_kwargs]) if n[:case_kwargs]
+          [item]
+        elsif n[:funcall_name]
+          [{kind: :funcall, name: n[:funcall_name].to_s, kwargs: extract_kwargs(n[:funcall_kwargs])}]
+        elsif n[:dep]
+          [{kind: :run, dependency: ident(n[:dep]), stage: ident(n[:stage])}]
+        elsif n[:run_stage_only]
+          [{kind: :run, dependency: nil, stage: ident(n[:run_stage_only][:stage])}]
+        elsif n[:bare_rule]
+          [{kind: :bare_rule, rule: extract_rule(n[:bare_rule])}]
+        elsif n[:comment]
+          []
+        elsif n[:noop]
+          []
+        else
+          []
+        end
+      end
+
+      # Filter out noop rules (from: None, to: None) created by empty
+      # parallel/sequence blocks that contain only comments or whitespace.
+      def filter_noop(rules)
+        rules.reject do |r|
+          r.is_a?(Hash) &&
+            r[:from].is_a?(Items::None) &&
+            r[:to].is_a?(Items::None)
+        end
+      end
+
+      def extract_rule(r)
+        from_val = r.is_a?(Hash) ? r[:from] : nil
+        to_val = r.is_a?(Hash) ? r[:to] : nil
+        constraints_val = r.is_a?(Hash) ? r[:constraints] : nil
+        {
+          from: from_val ? materialize(from_val) : Items::None.new,
+          to: to_val ? materialize(to_val) : Items::None.new,
+          constraints: extract_constraints(constraints_val)
+        }
+      end
+
+      def extract_constraints(arr)
+        Array(arr).map do |c|
+          # c is a one-key hash like { before: <item> }. Apply Transform to
+          # get { kind: :before, item: <materialized> }.
+          transformed = @transform.apply(c)
+          if transformed.is_a?(Hash) && transformed.key?(:kind)
+            transformed
+          else
+            # Transform rule didn't match — likely an empty/None constraint.
+            {kind: nil, item: nil}
+          end
+        end
+      end
+
+      def extract_dependency(item)
+        {
+          target: unquote(item[:target]),
+          alias: item[:alias] && ident(item[:alias])
+        }.compact
+      end
+
+      # Convert a grammar tree fragment into a concrete Item object via
+      # Transform. Reuses the builder's Transform instance — allocating
+      # one per fragment dominated large-map builds.
+      def materialize(fragment)
+        case fragment
+        when Hash
+          if fragment.key?(:concatenation)
+            @transform.apply(fragment)
+          else
+            @transform.apply(concatenation: [fragment])
+          end
+        when Array
+          @transform.apply(concatenation: fragment)
+        when NilClass
+          Items::None.new
+        else
+          fragment
+        end
+      end
+    end
+  end
+end

data/lib/interscript/isc/generator.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Interscript
+  module Isc
+    # Serializes a Node::Document back to ISC source — the inverse of
+    # Parser + DocumentBuilder + NodeAdapter. The Python compiler
+    # bridge generates ISC from in-memory documents because the
+    # rewritten python runtime executes ISC sources, not compiled
+    # modules. Every construct the generator emits must round-trip:
+    # spec/interscript/isc/generator_spec.rb pins behavior equality.
+    class Generator
+      def self.generate(doc)
+        new(doc).generate
+      end
+
+      def initialize(doc)
+        @doc = doc
+      end
+
+      def generate
+        out = "system #{quote(@doc.name.to_s)} {\n"
+        out << generate_aliases
+        out << generate_dependencies
+        @doc.stages.each do |name, group|
+          out << "  stage #{name} {\n" << generate_group(group, 2) << "  }\n"
+        end
+        out << "}\n"
+      end
+
+      private
+
+      def generate_aliases
+        return "" if @doc.aliases.empty?
+
+        out = +"  aliases {\n"
+        @doc.aliases.each_value do |alias_def|
+          out << "    #{alias_def.name} = #{item(alias_def.data)}\n"
+        end
+        out << "  }\n"
+      end
+
+      def generate_dependencies
+        return "" if @doc.dependencies.empty?
+
+        out = +""
+        @doc.dependencies.each do |dep|
+          out << "  dependency #{quote(dep.full_name.to_s)}"
+          out << " as #{dep.name}" if dep.name
+          out << "\n"
+        end
+        out
+      end
+
+      def generate_group(group, indent)
+        Array(group.children).map { |child| emit(child, indent) }.join
+      end
+
+      def emit(child, indent)
+        pad = " " * indent
+        case child
+        when Interscript::Node::Group::Parallel
+          "#{pad}parallel {\n#{generate_group(child, indent + 2)}#{pad}}\n"
+        when Interscript::Node::Group
+          generate_group(child, indent)
+        when Interscript::Node::Rule::Sub
+          rule(child, pad)
+        when Interscript::Node::Rule::Run
+          "#{pad}run #{run_target(child)}\n"
+        when Interscript::Node::Rule::Funcall
+          funcall(child, pad)
+        else
+          raise UnsupportedConstruct, "cannot generate #{child.class} as a stage item"
+        end
+      end
+
+      def rule(sub, pad)
+        out = "#{pad}sub {\n"
+        out << "#{pad}  from #{item(sub.from)}\n"
+        out << "#{pad}  to #{target(sub.to)}\n"
+        {before: sub.before, after: sub.after,
+         not_before: sub.not_before, not_after: sub.not_after}.each do |kw, value|
+          out << "#{pad}  #{kw} #{item(value)}\n" if value
+        end
+        out << "#{pad}}\n"
+      end
+
+      def target(to)
+        return to.to_s if %i[upcase downcase].include?(to)
+
+        item(to)
+      end
+
+      def run_target(run)
+        stage = run.stage
+        stage.map ? "map.#{stage.map}.stage.#{stage.name}" : "stage.#{stage.name}"
+      end
+
+      def funcall(rule, pad)
+        case rule.name
+        when :separate
+          separator = rule.kwargs[:separator]
+          return "#{pad}separate\n" if separator.nil?
+
+          "#{pad}separate separator #{item(separator)}\n"
+        when :title_case
+          word_separator = rule.kwargs[:word_separator]
+          return "#{pad}title_case\n" if word_separator.nil?
+
+          "#{pad}title_case word_separator: #{quote(word_separator)}\n"
+        else
+          unless rule.kwargs.empty?
+            raise UnsupportedConstruct,
+              "cannot generate #{rule.name}(...) with kwargs as ISC"
+          end
+
+          "#{pad}#{rule.name}\n"
+        end
+      end
+
+      # -- items --
+
+      def item(i)
+        case i
+        when Interscript::Node::Item::String
+          quote(i.data)
+        when Interscript::Node::Item::Any
+          any(i)
+        when Interscript::Node::Item::Alias
+          i.map ? "#{i.map}.#{identifier(i.name)}" : identifier(i.name)
+        when Interscript::Node::Item::CaptureGroup
+          "capture(#{item(i.data)})"
+        when Interscript::Node::Item::CaptureRef
+          "ref(#{i.id})"
+        when Interscript::Node::Item::Group
+          i.children.map { |c| item(c) }.join(" + ")
+        when Interscript::Node::Item::Maybe
+          "maybe(#{item(i.data)})"
+        when Interscript::Node::Item::Some
+          "some(#{item(i.data)})"
+        when ::String
+          quote(i)
+        when ::Symbol
+          identifier(i)
+        else
+          raise UnsupportedConstruct, "cannot generate #{i.class} as an item"
+        end
+      end
+
+      def any(node)
+        case node.value
+        when ::String
+          "any(#{quote(node.value)})"
+        when ::Range
+          "any(#{quote(node.value.first)}..#{quote(node.value.last)})"
+        when ::Array
+          inner = node.value.map { |v| item(v) }
+          return "any(#{inner.first})" if inner.size == 1
+
+          "any([#{inner.join(", ")}])"
+        else
+          raise UnsupportedConstruct, "cannot generate Any of #{node.value.class}"
+        end
+      end
+
+      def identifier(sym)
+        name = sym.to_s
+        raise UnsupportedConstruct, "#{name.inspect} is not a bare identifier" unless /\A[A-Za-z_][A-Za-z0-9_]*\z/.match?(name)
+
+        name
+      end
+
+      ESCAPE_MAP = {
+        "\\" => "\\\\",
+        "\"" => "\\\""
+      }.freeze
+
+      def quote(str)
+        escaped = str.to_s.gsub(/[\\"]/) { |c| ESCAPE_MAP.fetch(c) }
+        # Only control and DEL characters need escaping; both parsers
+        # read raw UTF-8, including astral code points (surrogate-pair
+        # \u escapes are NOT re-joined).
+        escaped = escaped.each_char.map { |c|
+          (c.ord < 0x20 || c.ord == 0x7f) ? format("\\u%04x", c.ord) : c
+        }.join
+        "\"" + escaped + "\""
+      end
+
+      class UnsupportedConstruct < StandardError; end
+    end
+  end
+end

data/lib/interscript/isc/grammar/concerns/aliases.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "parsanol"
+
+module Interscript
+  module Isc
+    module Grammar
+      module Concerns
+        # Aliases block: named expressions reused throughout the system.
+        module Aliases
+          include Parsanol
+
+          rule(:aliases_block) do
+            str("aliases") >> whitespace? >>
+              braced(alias_decl.repeat(0)).as(:aliases)
+          end
+
+          rule(:alias_decl) do
+            whitespace? >>
+              identifier.as(:name) >> whitespace? >>
+              str("=") >> whitespace? >>
+              item.as(:value) >>
+              whitespace?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/interscript/isc/grammar/concerns/dependencies.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "parsanol"
+
+module Interscript
+  module Isc
+    module Grammar
+      module Concerns
+        # Dependencies: references to other systems whose stages may be invoked.
+        module Dependencies
+          include Parsanol
+
+          rule(:dependency_decl) do
+            str("dependency") >> whitespace >>
+              quoted_string.as(:target) >>
+              (whitespace >> str("as") >> whitespace >>
+                identifier.as(:alias)).maybe
+          end
+        end
+      end
+    end
+  end
+end