interscript 2.4.5 → 3.0.0

data/lib/interscript/isc/parser.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "parsanol"
+
+module Interscript
+  module Isc
+    # Entry point for parsing ISC source files.
+    #
+    #   tree = Interscript::Isc::Parser.parse(source)
+    #   # => { system: { system_code: "...", body: [...] } }
+    #
+    # The returned tree is a parslet-shaped hash — lists of hashes with
+    # symbol keys. Convert to a domain object via Interscript::Isc::DocumentBuilder.
+    class Parser < Parsanol::Parser
+      include Grammar::Core
+
+      root :isc_source
+
+      # The compiled grammar, shipped alongside the .parg source; the
+      # runtime parses through it when parsanol carries PARG (>= 1.3.61)
+      # and falls back to the Ruby-DSL grammar otherwise. Trees are
+      # byte-identical by the corpus gate in the parg_diff spec.
+      ARTIFACT_PATH = File.expand_path("grammar/isc.artifact.json", __dir__)
+
+      class ArtifactUnavailable < StandardError; end
+
+      class << self
+        def parse(source, filename: nil)
+          parse_with_callbacks(source, filename: filename)
+        end
+
+        def parse_with_callbacks(source, filename: nil)
+          tree = begin
+            parse_with_artifact(source)
+          rescue ArtifactUnavailable
+            parse_with_dsl(source)
+          end
+          Normalizer.normalize(tree)
+        rescue Parsanol::ParseFailed => e
+          raise ParseError.new(e.message, filename: filename, source: source, cause: e)
+        end
+
+        def parse_with_artifact(source)
+          artifact.parse("isc", source)
+        end
+
+        def parse_with_dsl(source)
+          new.parse(source)
+        end
+
+        def artifact
+          @artifact ||= begin
+            require "parsanol/parg"
+            Parsanol::PARG::Artifact.load(ARTIFACT_PATH)
+          rescue LoadError, StandardError => e
+            raise ArtifactUnavailable, "parg artifact unavailable: #{e.class}: #{e.message}"
+          end
+        end
+
+        def reset_artifact
+          @artifact = nil
+        end
+      end
+    end
+
+    class ParseError < StandardError
+      attr_reader :filename, :source
+
+      def initialize(message, filename:, source:, cause: nil)
+        @filename = filename
+        @source = source
+        @cause = cause
+        loc = filename ? "#{filename}: " : ""
+        super("#{loc}#{message}")
+      end
+    end
+  end
+end

data/lib/interscript/isc/serializer.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "interscript/isc/items"
+
+module Interscript
+  module Isc
+    # Serializes a document hash back to ISC source text.
+    # This is the reverse of Parser → DocumentBuilder.
+    #
+    #   isc_source = Serializer.serialize(doc_hash)
+    #
+    class Serializer
+      def self.serialize(doc_hash)
+        new(doc_hash).serialize
+      end
+
+      def initialize(doc_hash)
+        @doc = doc_hash
+        @out = +""
+      end
+
+      def serialize
+        emit_system_open
+        emit_metadata if @doc[:metadata]&.any?
+        emit_tests if @doc[:tests]&.any?
+        emit_aliases if @doc[:aliases]&.any?
+        emit_dependencies if @doc[:dependencies]&.any?
+        emit_stages
+        emit_system_close
+        @out
+      end
+
+      private
+
+      def emit_system_open
+        @out << %(system "#{@doc[:systemCode]}" {\n)
+      end
+
+      def emit_system_close
+        @out << "}\n"
+      end
+
+      def emit_blank
+        @out << "\n"
+      end
+
+      def emit_metadata
+        @out << "\nmetadata {\n"
+        @doc[:metadata].each do |key, val|
+          emit_metadata_field(key, val)
+        end
+        @out << "}\n"
+      end
+
+      def emit_metadata_field(key, val)
+        k = key.to_s
+        case k
+        when "description"
+          emit_description(val)
+        when "notes", "implementation_notes", "original_notes"
+          emit_notes(k, val)
+        else
+          case val
+          when Array
+            val.each { |v| @out << "  #{k} #{emit_meta_value(v)}\n" }
+          when String
+            @out << "  #{k} #{emit_meta_value(val)}\n"
+          when NilClass
+            @out << "  #{k}\n"
+          else
+            @out << "  #{k} #{val}\n"
+          end
+        end
+      end
+
+      def emit_description(val)
+        s = val.is_a?(Array) ? val.join(" ") : val.to_s
+        s = s.strip
+        if s.empty?
+          @out << "  description { }\n"
+        elsif s.include?("\n") || s.length > 60
+          escaped = s.gsub("\\", "\\\\\\\\").gsub("{", "\\{").gsub("}", "\\}")
+          @out << "  description {\n    #{escaped.split("\n").join("\n    ")}\n  }\n"
+        else
+          @out << "  description { #{s.gsub("\\", "\\\\\\\\").gsub("{", "\\{").gsub("}", "\\}")} }\n"
+        end
+      end
+
+      def emit_notes(key, val)
+        arr = Array(val).compact.reject(&:empty?)
+        if arr.empty?
+          @out << "  #{key} { }\n"
+        else
+          @out << "  #{key} {\n"
+          arr.each do |note|
+            escaped = note.to_s.gsub("\\", "\\\\\\\\").gsub('"', '\\"')
+            @out << "    note \"#{escaped}\"\n"
+          end
+          @out << "  }\n"
+        end
+      end
+
+      def emit_meta_value(val)
+        s = val.to_s
+        # Quote values that contain spaces, special chars, or look like numbers
+        if s.match?(/[\s"{}#]/) || s.empty?
+          s.inspect
+        else
+          s
+        end
+      end
+
+      def emit_tests
+        @out << "\ntests {\n"
+        @doc[:tests].each do |t|
+          @out << %(  "#{escape(t[:input])}" -> "#{escape(t[:expected])}")
+          @out << %( note "#{escape(t[:note])}") if t[:note]
+          @out << "\n"
+        end
+        @out << "}\n"
+      end
+
+      def emit_aliases
+        @out << "\naliases {\n"
+        @doc[:aliases].each do |a|
+          @out << "  #{a[:name]} = #{emit_item(a[:value])}\n"
+        end
+        @out << "}\n"
+      end
+
+      def emit_dependencies
+        @doc[:dependencies].each do |d|
+          dep = %(dependency "#{d[:target]}")
+          dep << %( as #{d[:alias]}) if d[:alias]
+          @out << dep << "\n"
+        end
+        @out << "\n" if @doc[:dependencies].any?
+      end
+
+      def emit_stages
+        @doc[:stages].each do |stage|
+          @out << "\nstage #{stage[:name]} {\n"
+          stage[:body].each { |item| emit_stage_item(item) }
+          @out << "}\n"
+        end
+      end
+
+      def emit_stage_item(item)
+        case item[:kind]
+        when :parallel
+          @out << "  parallel {\n"
+          item[:rules].each { |r| emit_rule(r, 4) }
+          @out << "  }\n"
+        when :sequence
+          @out << "  sequence {\n"
+          item[:rules].each { |r| emit_rule(r, 4) }
+          @out << "  }\n"
+        when :bare_rule
+          emit_rule(item[:rule], 2)
+        when :run
+          dep = item[:dependency]
+          stage = item[:stage]
+          @out << if dep
+            "  run map.#{dep}.stage.#{stage}\n"
+          else
+            "  run stage.#{stage}\n"
+          end
+        when :separate
+          sep = item[:separator]
+          @out << "  separate separator #{emit_item(sep)}\n"
+        when :compose
+          @out << "  compose\n"
+        when :string_case
+          @out << "  #{item[:op]}\n"
+        end
+      end
+
+      def emit_rule(rule, indent)
+        pad = " " * indent
+        from_str = emit_item(rule[:from])
+        to_str = emit_item(rule[:to])
+
+        needs_block = rule[:from].is_a?(Items::Concat) || rule[:to].is_a?(Items::Concat)
+
+        if needs_block
+          inner = " " * (indent + 2)
+          @out << "#{pad}sub {\n"
+          @out << "#{inner}from #{from_str}\n"
+          @out << "#{inner}to #{to_str}\n"
+          rule[:constraints]&.each { |c| @out << "#{inner}#{emit_constraint(c)}\n" }
+          @out << "#{pad}}\n"
+        else
+          constraints_str = rule[:constraints]&.map { |c| emit_constraint(c) }&.join(" ") || ""
+          @out << "#{pad}sub #{from_str} #{to_str}"
+          @out << " #{constraints_str}" unless constraints_str.empty?
+          @out << "\n"
+        end
+      end
+
+      def emit_constraint(constraint)
+        "#{constraint[:kind]} #{emit_item(constraint[:item])}"
+      end
+
+      def emit_item(item)
+        return "none" unless item
+
+        case item
+        when Items::StringValue
+          escape_string(item.value)
+        when Items::None
+          "none"
+        when Items::Primitive
+          item.name
+        when Items::Function
+          item.name
+        when Items::AliasRef
+          item.name
+        when Items::Capture
+          "ref(#{item.index})"
+        when Items::CaptureGroup
+          "capture(#{emit_item(item.inner)})"
+        when Items::Concat
+          item.parts.map { |p| emit_item(p) }.join(" + ")
+        when Items::Set
+          %(any("#{item.chars.map { |c| escape(c) }.join}"))
+        when Items::Range
+          %(any("#{escape(item.lo)}".."#{escape(item.hi)}"))
+        when Items::Maybe
+          "maybe(#{emit_item(item.inner)})"
+        when Items::Some
+          "some(#{emit_item(item.inner)})"
+        else
+          item.to_s
+        end
+      end
+
+      def escape_string(str)
+        return '""' if str.nil?
+        escaped = str.gsub("\\", "\\\\\\\\").gsub('"', '\\"')
+        "\"#{escaped}\""
+      end
+
+      def escape(str)
+        str.to_s.gsub("\\", "\\\\\\\\").gsub('"', '\\"')
+      end
+    end
+  end
+end

data/lib/interscript/isc/transform.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "parsanol"
+
+module Interscript
+  module Isc
+    # Transforms the raw parslet tree into a clean intermediate hash with
+    # stable shape for the DocumentBuilder to consume.
+    #
+    # String escapes are unescaped here. Items are flattened. Constraints
+    # are tagged by kind.
+    class Transform < Parsanol::Transform
+      # String atom: parslet gives us a parslet slice for simple strings,
+      # or an array of pieces (escape-sequence fragments interleaved with
+      # raw chars) for strings containing escapes. Flatten both to a single
+      # StringValue.
+      rule(string: simple(:s)) { Items::StringValue.new(s.to_s) }
+      rule(string: sequence(:parts)) do
+        Items::StringValue.new(Transform.decode_string_parts(parts))
+      end
+      rule(run: simple(:s)) { s.to_s }
+
+      rule(identifier: simple(:i)) { i.to_s }
+
+      rule(none: simple(:_)) { Items::None.new }
+      # any_character is the Stdlib any-char alias (".") — without this
+      # rule the fragment stringified to "any_charany_character".
+      rule(any_char: simple(:_)) { Items::AliasRef.new("any_character") }
+      rule(primitive: simple(:p)) { Items::Primitive.new(p.to_s) }
+      rule(function: simple(:f)) { Items::Function.new(f.to_s) }
+      rule(alias: {identifier: simple(:n), qualified_name: simple(:q)}) {
+        Items::AliasRef.new(q.to_s, map: n.to_s)
+      }
+      rule(alias: simple(:n)) { Items::AliasRef.new(n.to_s) }
+      # Bare identifiers inside any(...) lists parse as :alias_ref (the
+      # :alias key only covers direct item position). Unmatched, the hash
+      # degraded downstream into the debug string "[:alias_ref, \"name\"]".
+      rule(alias_ref: {identifier: simple(:n)}) { Items::AliasRef.new(n.to_s) }
+      rule(alias_ref: simple(:n)) { Items::AliasRef.new(n.to_s) }
+      rule(ref: subtree(:h)) { Items::Capture.new(h[:digit].to_s.to_i) }
+      rule(capture_inner: subtree(:inner)) { Items::CaptureGroup.new(Interscript::Isc::Transform.materialize_item(inner)) }
+      rule(maybe_inner: subtree(:inner)) { Items::Maybe.new(Interscript::Isc::Transform.materialize_item(inner)) }
+      rule(some_inner: subtree(:inner)) { Items::Some.new(Interscript::Isc::Transform.materialize_item(inner)) }
+
+      rule(dquote: simple(:_)) { '"' }
+      rule(backslash: simple(:_)) { "\\" }
+      rule(newline: simple(:_)) { "\n" }
+      rule(carriage_return: simple(:_)) { "\r" }
+      rule(tab: simple(:_)) { "\t" }
+      rule(u_lone: simple(:_)) { "U" }
+      rule(unicode: simple(:hex)) do
+        [hex.to_s.to_i(16)].pack("U")
+      rescue
+        hex.to_s
+      end
+
+      # Shared decoder for the pieces of a :string capture — used by the
+      # transform rules above and by the Normalizer's scalar folding. A
+      # fragment without an escape key is a raw run slice.
+      def self.decode_string_parts(parts)
+        Array(parts).map do |p|
+          case p
+          when Hash
+            if p.key?(:run)
+              p[:run].to_s
+            elsif p.key?(:newline)
+              "\n"
+            elsif p.key?(:carriage_return)
+              "\r"
+            elsif p.key?(:tab)
+              "\t"
+            elsif p.key?(:dquote)
+              '"'
+            elsif p.key?(:backslash)
+              "\\"
+            elsif p.key?(:unicode)
+              [p[:unicode].to_s.to_i(16)].pack("U")
+            elsif p.key?(:u_lone)
+              "U"
+            else
+              p.to_s
+            end
+          else
+            p.to_s
+          end
+        end.join
+      end
+
+      rule(lo: simple(:lo), hi: simple(:hi)) do
+        Items::Range.new(lo.to_s, hi.to_s)
+      end
+      rule(single: simple(:s)) { Items::Set.from_string(s.to_s) }
+      # List entries are already Items (strings, primitives, alias refs).
+      # Stringifying here baked an object inspect into the char set.
+      rule(list: sequence(:arr)) do
+        Items::Set.new(arr)
+      end
+      rule(any: subtree(:h)) do
+        # A single alias argument keeps set semantics: the legacy runtime
+        # builds Any(Alias) which resolves through Stdlib (Any(nil) for
+        # imported aliases). Unwrapped, the bare Alias resolves to the
+        # imported charset string and compiles as a literal.
+        h.is_a?(Items::AliasRef) ? Items::Set.new([h]) : h
+      end
+
+      rule(concatenation: subtree(:parts)) do
+        Items::Concat.from_parts(Array(parts))
+      end
+
+      def self.materialize_item(fragment)
+        case fragment
+        when Hash
+          if fragment.key?(:concatenation)
+            new.apply(fragment)
+          else
+            new.apply(concatenation: [fragment])
+          end
+        when Array
+          new.apply(concatenation: fragment)
+        when NilClass
+          Items::None.new
+        else
+          fragment
+        end
+      end
+
+      def materialize_item(fragment)
+        self.class.materialize_item(fragment)
+      end
+
+      rule(before: subtree(:x)) { {kind: :before, item: x} }
+      rule(after: subtree(:x)) { {kind: :after, item: x} }
+      rule(not_before: subtree(:x)) { {kind: :not_before, item: x} }
+      rule(not_after: subtree(:x)) { {kind: :not_after, item: x} }
+      rule(constraints: sequence(:c)) { c }
+    end
+  end
+end

data/lib/interscript/isc/yaml_bridge.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require "interscript/isc/model"
+require "interscript/isc/items"
+
+module Interscript
+  module Isc
+    # Bridges the ISC document hash (from DocumentBuilder) and lutaml-model
+    # objects for YAML serialization.
+    #
+    #   yaml_str = YamlBridge.to_yaml(doc_hash)
+    #   doc_hash = YamlBridge.from_yaml(yaml_str)
+    #
+    module YamlBridge
+      class << self
+        def to_yaml(doc_hash)
+          hash_to_model(doc_hash).to_yaml
+        end
+
+        def from_yaml(yaml_str)
+          model_to_hash(Model::Document.from_yaml(yaml_str))
+        end
+
+        private
+
+        def hash_to_model(doc_hash)
+          Model::Document.new(
+            system_code: doc_hash[:systemCode],
+            metadata: normalize_metadata(doc_hash[:metadata]),
+            tests: (doc_hash[:tests] || []).map { |t| Model::Test.new(t.transform_keys(&:to_s)) },
+            aliases: (doc_hash[:aliases] || []).map { |a| build_alias_model(a) },
+            stages: (doc_hash[:stages] || []).map { |s| build_stage_model(s) },
+            dependencies: (doc_hash[:dependencies] || []).map { |d| build_dependency_model(d) }
+          )
+        end
+
+        def normalize_metadata(meta)
+          return {} unless meta.is_a?(Hash)
+          meta.transform_values do |v|
+            case v
+            when Array then v.map { |i| normalize_meta_value(i) }
+            else normalize_meta_value(v)
+            end
+          end.transform_keys(&:to_s)
+        end
+
+        def normalize_meta_value(v)
+          v.is_a?(Symbol) ? v.to_s : v
+        end
+
+        def build_alias_model(alias_hash)
+          Model::Alias.new(
+            name: alias_hash[:name],
+            value: item_to_model(alias_hash[:value])
+          )
+        end
+
+        def build_stage_model(stage_hash)
+          Model::Stage.new(
+            name: stage_hash[:name],
+            body: (stage_hash[:body] || []).map { |item| stage_item_to_model(item) }
+          )
+        end
+
+        def build_dependency_model(dep_hash)
+          Model::Dependency.new(
+            target: dep_hash[:target],
+            alias_name: dep_hash[:alias]
+          )
+        end
+
+        def stage_item_to_model(item)
+          attrs = {kind: item[:kind].to_s}
+          case item[:kind]
+          when :parallel, :sequence
+            attrs[:rules] = item[:rules].map { |r| rule_to_model(r) }
+          when :bare_rule
+            attrs[:rule] = rule_to_model(item[:rule])
+          when :run
+            attrs[:dependency] = item[:dependency]
+            attrs[:stage] = item[:stage]
+          when :separate
+            attrs[:separator] = item[:separator] ? item_to_model(item[:separator]) : nil
+          when :string_case
+            attrs[:op] = item[:op]
+          end
+          Model::StageItem.new(attrs.compact)
+        end
+
+        def rule_to_model(rule_hash)
+          Model::Rule.new(
+            from: item_to_model(rule_hash[:from]),
+            to: item_to_model(rule_hash[:to]),
+            constraints: (rule_hash[:constraints] || []).map { |c| constraint_to_model(c) }
+          )
+        end
+
+        def constraint_to_model(constraint_hash)
+          Model::Constraint.new(
+            kind: constraint_hash[:kind]&.to_s,
+            item: constraint_hash[:item] ? item_to_model(constraint_hash[:item]) : nil
+          )
+        end
+
+        # Convert an Items::* object to a Model::Item
+        def item_to_model(item)
+          return nil unless item
+
+          case item
+          when Items::StringValue
+            Model::Item.new(type: "string", value: item.value)
+          when Items::None
+            Model::Item.new(type: "none")
+          when Items::Primitive
+            Model::Item.new(type: "primitive", name: item.name)
+          when Items::Function
+            Model::Item.new(type: "function", name: item.name)
+          when Items::AliasRef
+            Model::Item.new(type: "alias_ref", name: item.name)
+          when Items::Capture
+            Model::Item.new(type: "capture", index: item.index)
+          when Items::CaptureGroup
+            Model::Item.new(type: "capture_group", inner: item_to_model(item.inner))
+          when Items::Maybe
+            Model::Item.new(type: "maybe", inner: item_to_model(item.inner))
+          when Items::Some
+            Model::Item.new(type: "some", inner: item_to_model(item.inner))
+          when Items::Range
+            Model::Item.new(type: "range", lo: item.lo, hi: item.hi)
+          when Items::Set
+            Model::Item.new(type: "set", chars: item.chars)
+          when Items::Concat
+            Model::Item.new(type: "concat", parts: item.parts.map { |p| item_to_model(p) })
+          else
+            Model::Item.new(type: "unknown", value: item.to_s)
+          end
+        end
+
+        # --- Reverse direction: model → document hash ---
+
+        def model_to_hash(model)
+          {
+            schemaVersion: 1,
+            systemCode: model.system_code,
+            metadata: model_metadata_to_hash(model.metadata),
+            tests: (model.tests || []).map { |t| {input: t.input || "", expected: t.expected || "", note: t.note}.compact },
+            aliases: (model.aliases || []).map { |a| {name: a.name, value: model_to_item(a.value)} },
+            stages: (model.stages || []).map { |s| stage_model_to_hash(s) },
+            dependencies: (model.dependencies || []).map { |d| {target: d.target, alias: d.alias_name}.compact }
+          }
+        end
+
+        def model_metadata_to_hash(meta)
+          return {} unless meta.is_a?(Hash)
+          meta.transform_keys(&:to_sym)
+        end
+
+        def stage_model_to_hash(stage_model)
+          {
+            name: stage_model.name,
+            body: stage_model.body.map { |item| stage_item_model_to_hash(item) }
+          }
+        end
+
+        def stage_item_model_to_hash(item)
+          case item.kind
+          when "parallel", "sequence"
+            {kind: item.kind.to_sym, rules: item.rules.map { |r| rule_model_to_hash(r) }}
+          when "bare_rule"
+            {kind: :bare_rule, rule: rule_model_to_hash(item.rule)}
+          when "run"
+            {kind: :run, dependency: item.dependency, stage: item.stage}
+          when "separate"
+            {kind: :separate, separator: item.separator ? model_to_item(item.separator) : nil}
+          when "compose"
+            {kind: :compose}
+          when "string_case"
+            {kind: :string_case, op: item.op}
+          else
+            {kind: item.kind&.to_sym}
+          end
+        end
+
+        def rule_model_to_hash(rule_model)
+          {
+            from: model_to_item(rule_model.from),
+            to: model_to_item(rule_model.to),
+            constraints: (rule_model.constraints || []).map { |c| constraint_model_to_hash(c) }
+          }
+        end
+
+        def constraint_model_to_hash(constraint_model)
+          {
+            kind: constraint_model.kind&.to_sym,
+            item: constraint_model.item ? model_to_item(constraint_model.item) : nil
+          }
+        end
+
+        # Convert a Model::Item back to an Items::* object
+        def model_to_item(item_model)
+          return nil unless item_model
+
+          case item_model.type
+          when "string"
+            Items::StringValue.new(item_model.value || "")
+          when "none"
+            Items::None.new
+          when "primitive"
+            Items::Primitive.new(item_model.name)
+          when "function"
+            Items::Function.new(item_model.name)
+          when "alias_ref"
+            Items::AliasRef.new(item_model.name)
+          when "capture"
+            Items::Capture.new(item_model.index)
+          when "capture_group"
+            Items::CaptureGroup.new(model_to_item(item_model.inner))
+          when "maybe"
+            Items::Maybe.new(model_to_item(item_model.inner))
+          when "some"
+            Items::Some.new(model_to_item(item_model.inner))
+          when "range"
+            Items::Range.new(item_model.lo, item_model.hi)
+          when "set"
+            Items::Set.new(item_model.chars || [])
+          when "concat"
+            Items::Concat.new((item_model.parts || []).map { |p| model_to_item(p) })
+          else
+            Items::StringValue.new(item_model.value.to_s)
+          end
+        end
+      end
+    end
+  end
+end