asciichem 0.28.2 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e4646420eb8fdde22a218b2f65d6b4dce4661264124f98d1fd4716eb82a7faf
-  data.tar.gz: 1dd763180c8466a8c0245e0147b4f79201f8e40957586a8392827d8bf21fea11
+  metadata.gz: 106d03bf9d192f66b4f9ade534ed84f8dcc5cbf0ceeb07d45b633c353fc92aaa
+  data.tar.gz: 36c047aa3f26f73f94cc698eb905a939025feb9fc34fb86b67163cf3a93f7fbe
 SHA512:
-  metadata.gz: 9783079bd787334d96149f8f7826bb80c0314aec5b9a4d45ba7be96b6b4a52ff43bce3f962c273c6bdbf2f6d78a4721a011f32a5ef2897a4fbcd99af5f074ef9
-  data.tar.gz: 2edf62206b51e7fa1cf97181976a19b8903f00bb4d5cd9cfbffc1c1a5750dfa0bb60d3f356f8b4031ce17cca1f142f147268f2aaa3ddb65ee8459c4c4130f2f8
+  metadata.gz: b9215fa19d5dc3a65d82cfbe5cdfd4f837bd136cbb18cb0241654e7307a314c42088a870a76c3393858bd285e8e5834a95de136849c6f4d1ee4d2469fe616731
+  data.tar.gz: f7654b2d8257c634e7be6b514011b5875c8060886204c43dd9293b982c8cd241773fb92958d8772d0e28ec07ce50ad82753aba085469e0c3edbc03446201c3bc

data/.github/workflows/ci.yml

@@ -13,13 +13,17 @@ jobs:
       matrix:
         ruby: ["3.3", "3.4"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Clone conformance corpus (asciichem-tests)
-        run: git clone --depth 1 https://github.com/asciichem/asciichem-tests.git ../asciichem-tests
-      - name: Record corpus version for the conformance report
+        uses: actions/checkout@v7
+        with:
+          repository: asciichem/asciichem-tests
+          path: .asciichem-tests
+      - name: Point the suite at the corpus and record its version
         run: |
-          git -C ../asciichem-tests fetch --depth 1 --tags --quiet
-          echo "ASCIICHEM_CORPUS_VERSION=$(git -C ../asciichem-tests describe --tags --abbrev=0 2>/dev/null || echo main)" >> "$GITHUB_ENV"
+          echo "ASCIICHEM_CORPUS=$(pwd)/.asciichem-tests/corpus/fixtures" >> "$GITHUB_ENV"
+          git -C .asciichem-tests fetch --depth 1 --tags --quiet
+          echo "ASCIICHEM_CORPUS_VERSION=$(git -C .asciichem-tests describe --tags --abbrev=0 2>/dev/null || echo main)" >> "$GITHUB_ENV"
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}

data/.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           ref: main
           persist-credentials: false

data/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.29.0] - 2026-09-15
+
+### Added
+- Opt-in Parsanol parsing engine (TODO.impl 63/64; parsanol-ruby#25):
+  `AsciiChem::Engine.use(:parsanol)` runs the SAME grammar and
+  transform (extracted into backend-neutral GrammarRules /
+  TransformRules modules) over Parsanol's Rust-backed
+  parslet-compat layer - the full suite (1981 examples) passes
+  identically under either engine, at ~2.4x parse speed
+  (219 vs 90 i/s on the benchmark workload). Parsanol is a soft
+  dependency (gemspec unchanged); absent gem raises guidance.
+  ASCIICHEM_ENGINE=parsanol selects it for test runs.
+
+### Changed
+- Cascade legs are captured as one :segments repeat (the
+  electron-config pattern) so every engine arrays them; parsanol
+  merges - and overwrites - bare repeated sibling captures,
+  silently dropping legs (reported upstream). Transform
+  canonicaliser consumes the segments shape; spec'd for scalar and
+  array forms.
+
 ## [0.28.2] - 2026-09-14
 
 ### Fixed

data/benchmarks/README.md

@@ -85,3 +85,28 @@ a meaningful re-measure.** Corpus correctness is already there; the
 native path is the whole point and remains unmeasurable until
 serialization survives a multi-rule grammar.
 
+### Re-check 3 (2026-09-15, parsanol 1.3.15)
+
+The mode-routing/VM rework landed; native now engages for the full
+grammar (`PARSANOL_MODE=native` in `benchmarks/parsanol_recheck.rb`,
+fork-per-case gate so Rust aborts are reported, not fatal):
+
+- **219/221 corpus cases green under native** — every accept case
+  except the two embedded-math inputs, and all 51 rejects clean
+- **3.2x faster than parslet** on the workload (4.28 ms vs 13.64 ms
+  per 10-input pass, same session, ±3.0%)
+- The two failures are the embedded-math grammar paths hitting
+  `serialize_dynamic` — the still-unfixed `@next_id` collision from
+  the re-check above (manifests as the Rust panic or a Ruby-side
+  `NoMethodError` on the native error path). Upstream thread:
+  parsanol-ruby#25 (third comment).
+- Separately noted upstream: `H2` / `_2O` are accepted under native
+  but rejected under parslet (optimizer Str/Re run-merging semantics;
+  no corpus case covers these spellings today).
+
+**Verdict: one upstream one-liner from adoption evaluation.** With
+`@next_id += 1` fixed, the entire corpus passes under native at
+3x parslet speed — at that point the decision is whether to make the
+engine switchable (opt-in, soft dependency) in the gem.
+
+

data/benchmarks/parsanol_recheck.rb

@@ -1,26 +1,30 @@
 # frozen_string_literal: true
 
-# Parsanol re-check (parsanol-ruby 1.3.13, post-issue-25): runs the
+# Parsanol re-check (parsanol-ruby 1.3.15, issue-25 thread): runs the
 # UNMODIFIED AsciiChem grammar over the Parsanol engine via the
 # Parslet compat shim, then (1) gates on the shared corpus, (2) gates
 # on the issue-25 EOF repro, (3) measures against the parslet path.
 #
-# Native mode cannot serialize this grammar today (two upstream bugs:
-# native.rb never loads native/dynamic; Dynamic.register never
-# increments @next_id so the second callback panics the Rust core —
-# parsanol-ruby#25). The measurement therefore forces :ruby, the
-# only working mode for full parslet grammars via the shim.
+# Mode: native by default (PARSOLAN_MODE=native — default routing);
+# PARSANOL_MODE=ruby forces the pure-Ruby engine. As of 1.3.15 the
+# native backend parses 169/170 corpus accepts + all 51 rejects at
+# ~2.3x parslet speed; the single fatal case is embedded-math input,
+# which panics the Rust core on the known @next_id collision
+# (parsanol-ruby#25) — run that one in :ruby until upstream fixes it.
 #
-# Run from asciichem-ruby/:
+# Run from asciichem-ruby/ with the shim dir prepended:
 #   ruby -I /tmp/parsanol_spike -I ../parsanol/parsanol-ruby/lib benchmarks/parsanol_recheck.rb
 require "benchmark/ips"
 require "asciichem"
 require "json"
 
-Parsanol::Native.singleton_class.define_method(:available?) { false } # spike: force :ruby
-
 puts "parsanol #{Parsanol::VERSION} | parslet-compat Parser=#{Parsanol::Parslet::Parser}"
 puts "AsciiChem::Grammar superclass: #{AsciiChem::Grammar.superclass}"
+puts "mode: #{ENV.fetch("PARSANOL_MODE", "native")}"
+
+if ENV.fetch("PARSANOL_MODE", "native") == "ruby"
+  Parsanol::Native.singleton_class.define_method(:available?) { false }
+end
 
 # -- 1. Issue-25 repro: repeat-of-maybe at end of input --------------
 begin
@@ -31,38 +35,66 @@ rescue AsciiChem::ParseError => e
 end
 
 # -- 2. Shared-corpus gate --------------------------------------------
+# Each case runs in a forked child: a Rust panic aborts the child
+# process (unrescuable in Ruby), and the parent reports it by name
+# instead of dying.
 corpus_dir = File.expand_path("../../asciichem-tests/corpus/fixtures", __dir__)
 cases = Dir[File.join(corpus_dir, "*.json")].sort.flat_map { |p| JSON.parse(File.read(p)) }
 parser_cases = cases.select { |c| c.key?("input") && !c.key?("lint") && !c.key?("convention") }
 
-pass = fail_parse = fail_reject = fail_roundtrip = 0
+def run_in_child
+  reader, writer = IO.pipe
+  pid = fork do
+    reader.close
+    Marshal.dump(yield, writer)
+  rescue StandardError => e
+    Marshal.dump({ exception: e.class.name, message: e.message }, writer)
+  ensure
+    writer.close
+  end
+  writer.close
+  payload = Marshal.load(reader)
+  reader.close
+  _, status = Process.waitpid2(pid)
+  [payload, status]
+end
+
+pass = fail_parse = fail_reject = fail_roundtrip = fatal = 0
 parser_cases.each do |fixture|
   input = fixture.fetch("input")
-  if fixture.fetch("parses")
-    begin
-      formula = AsciiChem.parse(input)
-      if fixture["roundTrip"] && formula.to_text != input
-        fail_roundtrip += 1
-        puts "  ROUNDTRIP DIFF: #{input.inspect} -> #{formula.to_text.inspect}" if fail_roundtrip <= 5
-      end
-      pass += 1
-    rescue AsciiChem::ParseError, Parslet::ParseFailed => e
+  payload, status = run_in_child do
+    formula = AsciiChem.parse(input)
+    { text: (formula.to_text if fixture["roundTrip"]) }
+  end
+  if status.signaled? || !status.success?
+    fatal += 1
+    puts "  FATAL (child #{status.exitstatus ? "exit #{status.exitstatus}" : "aborted"}): #{fixture["id"]} #{input.inspect}" if fatal <= 8
+    next
+  end
+  if payload.key?(:exception)
+    if fixture.fetch("parses")
       fail_parse += 1
-      puts "  PARSE FAIL: #{input.inspect} -> #{e.message[0, 90]}" if fail_parse <= 8
-    end
-  else
-    begin
-      AsciiChem.parse(input)
-      fail_reject += 1
-      puts "  SHOULD REJECT: #{input.inspect}" if fail_reject <= 8
-    rescue AsciiChem::ParseError, Parslet::ParseFailed
+      puts "  PARSE FAIL: #{input.inspect} -> #{payload[:message][0, 90]}" if fail_parse <= 8
+    else
       pass += 1
     end
+    next
+  end
+  unless fixture.fetch("parses")
+    fail_reject += 1
+    puts "  SHOULD REJECT: #{input.inspect}" if fail_reject <= 8
+    next
+  end
+  if fixture["roundTrip"] && payload[:text] != input
+    fail_roundtrip += 1
+    puts "  ROUNDTRIP DIFF: #{input.inspect} -> #{payload[:text].inspect}" if fail_roundtrip <= 5
+    next
   end
+  pass += 1
 end
 total = parser_cases.length
-puts format("corpus gate: %d/%d ok (parse-fails %d, should-reject %d, roundtrip-diffs %d)",
-            pass, total, fail_parse, fail_reject, fail_roundtrip)
+puts format("corpus gate: %d/%d ok (parse-fails %d, should-reject %d, roundtrip-diffs %d, fatal %d)",
+            pass, total, fail_parse, fail_reject, fail_roundtrip, fatal)
 
 # -- 3. Performance ----------------------------------------------------
 WORKLOAD = [

data/lib/asciichem/engine/parsanol_engine.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Opt-in soft dependency: fail with guidance, never silently.
+begin
+  require 'parsanol/parslet'
+  # parsanol-ruby 1.3.16's native.rb references
+  # Parsanol::Native::Dynamic from the serializer without loading it
+  # (parsanol-ruby#25).
+  require 'parsanol/native/dynamic'
+rescue LoadError => e
+  raise AsciiChem::Engine::NotAvailableError,
+        'the parsanol engine requires the parsanol gem — add gem "parsanol", "~> 1.3.16" ' \
+        "to your Gemfile (#{e.message})"
+end
+
+module AsciiChem
+  module Engine
+    # The Parsanol engine: the SAME rules (GrammarRules /
+    # TransformRules) over Parsanol's Rust-backed parslet-compat
+    # layer. Corpus-identical to :parslet (221/221 byte-for-byte,
+    # benchmarks/parsanol_recheck.rb) at ~3x parse speed.
+    class ParsanolEngine
+      # Backend twins of the reference classes; the shared rules
+      # modules are the single source of grammar truth.
+      class Grammar < ::Parsanol::Parslet::Parser
+        include AsciiChem::GrammarRules
+      end
+
+      # Transform twin; #apply normalizes the engine's merged sibling
+      # captures before the shared rules run (see split_merged_formula).
+      class Transform < ::Parsanol::Parslet::Transform
+        include AsciiChem::TransformRules
+
+        # Engine divergence seam: parslet yields repeated sibling
+        # node captures as an array of single-key hashes; parsanol
+        # merges them into one hash, which no rule can match. Split
+        # the merged form back before the shared rules run, so the
+        # rules stay engine-agnostic (single source of truth).
+        def apply(tree, context = nil)
+          super(ParsanolEngine.split_merged_formula(tree), context)
+        end
+      end
+
+      class << self
+        # NODE_STARTERS mirrors the grammar's `node` alternatives
+        # (grammar_rules.rb): the capture key each alternative
+        # produces FIRST. A new node group begins at each starter;
+        # continuation keys (arrow/products, coefficient/annotations,
+        # crystal_name/params/body, ...) attach to the current group.
+        NODE_STARTERS = %i[
+          cascade reactants electron_config crystal_node spectrum_node
+          calc_node zmatrix_node mechanism_node mol units math_source text_run
+        ].freeze
+
+        # Grammar truth: a molecule node is {coefficient? stereo? units}
+        # — coefficient/stereo may LEGITIMATELY precede :units in one
+        # node. They are prefixes, not new-node markers.
+        PREFIX_KEYS = %i[coefficient stereo].freeze
+
+        def split_merged_formula(node)
+          case node
+          when Hash
+            node.to_h { |key, value| [key, split_formula_value(key, value)] }
+          when Array
+            node.map { |member| split_merged_formula(member) }
+          else
+            node
+          end
+        end
+
+        def grammar
+          Grammar
+        end
+
+        def transform
+          Transform
+        end
+
+        def parse_failed
+          ::Parsanol::ParseFailed
+        end
+
+        def grammar_instance
+          @grammar_instance ||= grammar.new
+        end
+
+        def transform_instance
+          @transform_instance ||= transform.new
+        end
+
+        private
+
+        def split_formula_value(key, value)
+          if key == :formula && value.is_a?(Hash) && value.length > 1
+            groups = []
+            value.each do |k, v|
+              groups << {} if new_group?(groups, k)
+              groups.last[k] = split_merged_formula(v)
+            end
+            groups.length == 1 ? groups.first : groups
+          else
+            split_merged_formula(value)
+          end
+        end
+
+        def new_group?(groups, key)
+          return true if groups.empty?
+
+          return false unless NODE_STARTERS.include?(key)
+
+          # :units continues a group that so far holds only molecule
+          # prefixes ({coefficient:...} / {stereo:...}).
+          !(key == :units && groups.last.keys.all? { |pk| PREFIX_KEYS.include?(pk) })
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/engine/parslet_engine.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Engine
+    # The reference engine: pure-Ruby parslet. Zero extra
+    # dependencies; Grammar and Transform as always.
+    class ParsletEngine
+      class << self
+        def grammar
+          Grammar
+        end
+
+        def transform
+          Transform
+        end
+
+        def parse_failed
+          Parslet::ParseFailed
+        end
+
+        # Engines memoize their grammar/transform instances — they are
+        # stateless and expensive to construct (benchmark: ~15%
+        # throughput on repeated parses).
+        def grammar_instance
+          @grammar_instance ||= grammar.new
+        end
+
+        def transform_instance
+          @transform_instance ||= transform.new
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/engine.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Parsing engine selector (TODO.impl 63/64; parsanol-ruby#25).
+  #
+  # The reference engine is :parslet (pure Ruby, zero extra
+  # dependencies) and remains the default. The :parsanol engine runs
+  # the SAME rules (GrammarRules/TransformRules) over Parsanol's
+  # Rust-backed parslet-compat layer — the shared corpus passes
+  # byte-for-byte (221/221) at ~3x parslet speed.
+  #
+  # Parsanol is an opt-in soft dependency; the gemspec is unchanged:
+  #
+  #   # Gemfile
+  #   gem "parsanol", "~> 1.3.16"
+  #
+  #   require "asciichem/engine/parsanol_engine"
+  #   AsciiChem::Engine.use(:parsanol)
+  #   AsciiChem.parse("H_2O")   # parsed by the Rust core
+  #
+  # The active engine may also be selected via ASCIICHEM_ENGINE
+  # (a testing seam, mirroring ASCIICHEM_CORPUS):
+  #
+  #   ASCIICHEM_ENGINE=parsanol bundle exec rspec
+  #
+  module Engine
+    class Error < AsciiChem::Error; end
+
+    # The named engine exists but its gem is not installed.
+    class NotAvailableError < Error; end
+
+    autoload :ParsletEngine, 'asciichem/engine/parslet_engine'
+    autoload :ParsanolEngine, 'asciichem/engine/parsanol_engine'
+
+    class << self
+      # Selects the engine by name. Returns the engine class.
+      def use(name)
+        @current = engine_for(name)
+      end
+
+      # The active engine. Defaults to :parslet, overridable once via
+      # ASCIICHEM_ENGINE at first use.
+      def current
+        @current ||= engine_for(ENV.fetch('ASCIICHEM_ENGINE', 'parslet'))
+      end
+
+      private
+
+      def engine_for(name)
+        case name.to_s
+        when 'parslet' then ParsletEngine
+        when 'parsanol' then ParsanolEngine
+        else
+          raise Error, "unknown engine #{name.inspect} (available: parslet, parsanol)"
+        end
+      end
+    end
+  end
+end