asciichem 0.26.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54b5e13e60ca4236628c8b8a145add5991c347747b7d7e2aa24f6acda6d89ad1
-  data.tar.gz: 7b8b2380ea9e5030065958cf35148da3addf2c6dcfb3dd1428066fee088dc410
+  metadata.gz: 8fb92ff1cd35eeb546372b2ac9c3cf97b908971409e9a1d473b575479464e356
+  data.tar.gz: 2cc3be9f85b7ca2d7e3fe773e981073b6a755344cc6b593b1940666653fb52e7
 SHA512:
-  metadata.gz: 0f3f2ae54757260f1ad644d77415a557b16ccdcb15d80829775362fbd2194de3351327babf11ed662676fcfefcd6898a3e9d942928e4a831ac770bb8339846fe
-  data.tar.gz: 360208b6be6fc9666505610618e7a029711595c9ff353e3ef391e09f80619e47cafbe1304c15e2dffac7c15d436f016094e039ce6a02480393f967bbc9ab1edc
+  metadata.gz: 6d2f065122017d83a4e0fdb5a9da9db50a9dbd321e335a9f49bce5c3d253e78ae11f7ae33899ad4ce60fa28b9053a085f4cac7acefbd22999c88287fc0d38d2d
+  data.tar.gz: 369b73e26be9c6234fd36c6a2e5d14b53a8746a5fa44c7bc5949297cc17978e6a135e4f003a90641ad7e63a2ce4dd400e05107bb79157628028f14bc68104ac2

data/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.28.0] - 2026-09-14
+
+### Changed
+- Embedded-math MathML now crosses through the mml gem
+  (plurimath/mml) in both directions: Plurimath output is parsed
+  into a typed Mml::V3 graph and re-serialized by the framework
+  before grafting - replacing xpath surgery on the raw string.
+  mml (~> 2.3) is now a direct dependency (previously transitive
+  via plurimath).
+- New spec contract: every emitted MathML (and every shared-corpus
+  golden) parses back through Mml.parse - output is valid per the
+  typed MathML contract model, not just well-formed XML.
+
+## [0.27.0] - 2026-09-14
+
+### Added
+- Local InChI identity engine (TODO.impl 48 / TODO.v2 10): opt-in
+  `AsciiChem::Inchi` abstraction over the IUPAC `inchi-1` binary
+  (never reimplemented). `EngineMissingError` carries install
+  guidance. `IdentityCrossCheck` linter compares annotated
+  `@inchi`/`@inchikey` against the drawn structure (error with
+  engine, one guidance warning without). CLI: `asciichem identity`.
+- L2 MathML golden conformance: corpus suite pinned against the
+  reference goldens; report claims the level.
+
+### Fixed
+- Electron-configuration MathML separator is a real U+00A0 (was a
+  double-escaped entity artifact).
+- Reaction conditions render in-place through the same MathML
+  formatter (was serialize → reparse → graft, which leaked xmlns and
+  reset indentation).
+- Molecule stereo markers (`(R)-`, `(alpha)-`, …) survive the v1
+  wire form (additive optional `stereo` field; paired with
+  asciichem-model#13).
+
 ## [0.26.0] - 2026-09-14
 
 ### Added
@@ -483,3 +518,13 @@ This project follows [Semantic Versioning](https://semver.org/).
 [0.3.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/asciichem/asciichem-ruby/releases/tag/v0.1.0
+    ### Changed
+- Embedded-math MathML now crosses through the mml gem (plurimath/mml)
+  in both directions: Plurimath output is parsed into a typed
+  Mml::V3 graph and re-serialized by the framework before grafting —
+  replacing xpath surgery on the raw string. mml (~> 2.3) is now a
+  direct dependency (previously transitive via plurimath).
+- New spec contract: every emitted MathML (and every shared-corpus
+  golden) parses back through Mml.parse — output is valid per the
+  typed MathML contract model, not just well-formed XML.
+

data/asciichem.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "chemicalml", "~> 0.3.0"
   spec.add_dependency "elkrb", "~> 1.0"
   spec.add_dependency "lutaml-model", ">= 0.8", "< 2"
+  spec.add_dependency "mml", "~> 2.3"
   spec.add_dependency "nokogiri", "~> 1.16"
   spec.add_dependency "parslet", "~> 2.0"
   spec.add_dependency "relaton-bib", ">= 0.1", "< 2"

data/lib/asciichem/cli.rb

@@ -168,6 +168,31 @@ module AsciiChem
       exit 1
     end
 
+    desc "identity -i INPUT", "Derive InChI/InChIKey locally from the structure (offline; requires an InChI engine)"
+    method_option :input, aliases: "-i", type: :string,
+                           desc: "Source text (or '-' for stdin)"
+    method_option :file, aliases: "-f", type: :string,
+                          desc: "Read source from a file"
+    method_option :from, type: :string, default: "asciichem",
+                        desc: "Input grammar: asciichem|smiles|molfile"
+    method_option :engine_bin, type: :string,
+                               desc: "Path to the inchi-1 binary (overrides the configured engine)"
+    def identity
+      formula = ingest(read_source, options[:from])
+      molecules = molecules_in(formula)
+      unless molecules.length == 1
+        raise AsciiChem::Error, "identity derivation needs exactly one molecule, got #{molecules.length}"
+      end
+
+      engine = options[:engine_bin] ? AsciiChem::Inchi::BinaryEngine.new(bin: options[:engine_bin]) : nil
+      derived = AsciiChem::Inchi.identity_for(molecules.first, engine: engine)
+      puts derived.inchi
+      puts derived.inchikey if derived.inchikey
+    rescue AsciiChem::EngineMissingError, AsciiChem::Error => e
+      warn "Identity error: #{e.message}"
+      exit 5
+    end
+
     private
 
     def read_source
@@ -206,6 +231,19 @@ module AsciiChem
       AsciiChem::Formatter.render(format.to_sym, formula)
     end
 
+    # Molecules anywhere at the top level: direct formula nodes plus
+    # reaction terms. Identity derivation needs exactly one molecule.
+    def molecules_in(formula)
+      formula.nodes.flat_map do |node|
+        case node
+        when AsciiChem::Model::Reaction then node.reactants + node.products
+        when AsciiChem::Model::ReactionCascade
+          node.steps.flat_map { |step| step.reactants + step.products }
+        else [node]
+        end
+      end.grep(AsciiChem::Model::Molecule)
+    end
+
     def output_lint(diagnostics, format)
       case format.to_s
       when "json" then output_lint_json(diagnostics)

data/lib/asciichem/errors.rb

@@ -6,4 +6,9 @@ module AsciiChem
   class ParseError < Error; end
 
   class FormatError < Error; end
+
+  # No InChI engine is configured (or the engine binary is absent).
+  # Identity derivation is opt-in; the message always carries install
+  # guidance (TODO.v2 10: never a silent fallback or homemade InChI).
+  class EngineMissingError < Error; end
 end

data/lib/asciichem/formatter/mathml.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "nokogiri"
+require "mml"
 
 module AsciiChem
   module Formatter
@@ -186,7 +187,7 @@ module AsciiChem
       def visit_electron_configuration(ec)
         mrow = el("mrow")
         ec.orbitals.each_with_index do |(orbital, occupancy), index|
-          mrow.add_child(mo(" ")) if index.positive?
+          mrow.add_child(mo(" ")) if index.positive?
           msup = el("msup")
           msup.add_child(mi(orbital))
           msup.add_child(mn(occupancy))
@@ -196,17 +197,27 @@ module AsciiChem
       end
 
       def visit_embedded_math(em)
-        # Strip the outer <math> wrapper so the embedded fragment slots
-        # into our surrounding <mrow>.
-        fragment = em.formula.to_mathml
-        parsed = Nokogiri::XML(fragment)
-        math = parsed.at_xpath("//m:math", m: MATHML_NS)
-        return el("mrow") unless math
-
-        # Detach children into a fresh <mrow>.
+        # Embedded math crosses through the mml gem in both directions:
+        # Plurimath's MathML string is parsed into a typed Mml::V3
+        # graph (the MathML contract model), and each top-level child
+        # is re-serialized by the framework before grafting — never
+        # ad-hoc xpath surgery on the string.
+        math = Mml.parse(em.formula.to_mathml, version: 3)
         mrow = el("mrow")
-        math.children.each { |c| mrow.add_child(c.dup) }
+        math.element_order.each do |entry|
+          next unless entry.respond_to?(:name)
+
+          attr_name = xml_element_attribute(math.class, entry.name)
+          next unless attr_name
+
+          Array(math.public_send(attr_name)).each do |child|
+            fragment = Nokogiri::XML::DocumentFragment.parse(child.to_xml)
+            fragment.children.each { |node| mrow.add_child(node) }
+          end
+        end
         mrow
+      rescue Mml::Error, Lutaml::Model::Error, Nokogiri::XML::SyntaxError
+        el("mrow")
       end
 
       def visit_text(text)
@@ -309,6 +320,14 @@ module AsciiChem
 
       private
 
+      # Symbol of the model attribute an XML child element name maps
+      # to on a Mml class (e.g. "mstyle" => :mstyle_value), via the
+      # lutaml-model XML mapping — no name-munging.
+      def xml_element_attribute(klass, element_name)
+        rule = klass.mappings_for(:xml).elements.find { |r| r.name == element_name }
+        rule&.to
+      end
+
       def render_node(node)
         node.accept(self)
       end
@@ -338,25 +357,21 @@ module AsciiChem
       # Render a reaction-condition string. The condition is captured
       # as raw text by the grammar, but chemists expect `_N` and `^N`
       # patterns to render as proper sub/superscripts. We parse the
-      # condition as AsciiChem and use its MathML output. If the parse
-      # fails (e.g. the condition is free-form prose), fall back to
-      # plain <mtext>.
+      # condition as AsciiChem and render it in-place with this same
+      # formatter (no serialize/reparse round-trip, so no stray xmlns
+      # or reset indentation). If the parse fails (e.g. the condition
+      # is free-form prose), fall back to plain <mtext>.
       def render_condition(text)
         return mtext("") if text.nil? || text.empty?
 
         begin
-          inner = AsciiChem.parse(text).to_mathml
-          parsed = Nokogiri::XML(inner)
-          math = parsed.at_xpath("//m:math", m: MATHML_NS)
-          if math
-            mrow = el("mrow")
-            math.children.each { |c| mrow.add_child(c.dup) }
-            return mrow
-          end
+          formula = AsciiChem.parse(text)
+          mrow = el("mrow")
+          formula.nodes.each { |n| mrow.add_child(render_node(n)) }
+          mrow
         rescue AsciiChem::ParseError, AsciiChem::Error
-          # fall through to plain text
+          mtext(text)
         end
-        mtext(text)
       end
 
       def wrap_in_sub(base, sub)

data/lib/asciichem/inchi/binary_engine.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module AsciiChem
+  module Inchi
+    # Engine that shells out to the standalone IUPAC `inchi-1`
+    # binary. The binary is a documented external dependency — nothing
+    # is vendored (vendoring the InChI library requires the licence
+    # review recorded in TODO.v2 10, a maintainer decision).
+    #
+    #   AsciiChem::Inchi.engine = AsciiChem::Inchi::BinaryEngine.new
+    #   AsciiChem::Inchi.engine = AsciiChem::Inchi::BinaryEngine.new(bin: "/usr/local/bin/inchi-1")
+    class BinaryEngine < Engine
+      DEFAULT_FLAGS = %w[-STDIO -AuxNone -NoLabels -Key].freeze
+
+      attr_reader :bin, :flags
+
+      def initialize(bin: 'inchi-1', flags: DEFAULT_FLAGS)
+        super()
+        @bin = bin
+        @flags = flags.freeze
+      end
+
+      # model → molfile → inchi-1 → Identity. The molfile emission is
+      # the pipe: atom coordinates, charges and isotopes cross into
+      # the engine through the V2000 block.
+      def identity(molecule)
+        molfile = AsciiChem::Molfile.write(molecule)
+        out = execute(molfile)
+        inchi = out[/^InChI=\S+/]
+        raise AsciiChem::Error, "#{bin} produced no InChI:\n#{out}" unless inchi
+
+        inchikey = out[/^InChIKey=(\S+)/, 1]
+        raise AsciiChem::Error, "#{bin} produced no InChIKey (pass -Key):\n#{out}" unless inchikey
+
+        Identity.new(inchi: inchi, inchikey: inchikey)
+      end
+
+      private
+
+      def execute(input)
+        out, err, status = Open3.capture3(bin, *flags, stdin_data: input)
+        unless status.success?
+          raise AsciiChem::Error, "#{bin} failed (exit #{status.exitstatus}): #{(err + out).strip[0, 500]}"
+        end
+
+        out
+      rescue Errno::ENOENT
+        raise EngineMissingError, "InChI engine binary #{bin.inspect} not found — #{AsciiChem::Inchi::INSTALL_GUIDE}"
+      end
+    end
+  end
+end

data/lib/asciichem/inchi/engine.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Inchi
+    # Abstract identity engine. Subclasses wrap an InChI
+    # implementation (IUPAC software, RDKit, WASM build) behind one
+    # contract. Registering an engine is how a user opts in to local
+    # identity derivation — the core gem stays dependency-free.
+    class Engine
+      # The single engine obligation: return the Identity of a
+      # Model::Molecule.
+      def identity(_molecule)
+        raise NotImplementedError, "#{self.class} must implement #identity"
+      end
+
+      # Standard InChI string of the molecule (TODO.v2 10 interface).
+      def to_inchi(molecule, standard: true)
+        identity = identity(molecule)
+        return identity.inchi if standard
+
+        raise ArgumentError, "#{self.class} derives standard InChI only"
+      end
+
+      # InChIKey of the molecule.
+      def to_inchikey(molecule)
+        identity(molecule).inchikey
+      end
+    end
+  end
+end

data/lib/asciichem/inchi/identity.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Inchi
+    # Derived identity of a structure: the standard InChI string and
+    # its InChIKey. Value object returned by engines.
+    Identity = Struct.new(:inchi, :inchikey, keyword_init: true)
+  end
+end

data/lib/asciichem/inchi.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Local identity derivation (TODO.v2 10; TODO.impl 48).
+  #
+  # The InChI algorithm is never reimplemented: engines wrap the IUPAC
+  # reference software (the standalone `inchi-1` binary here). The pipe
+  # is Model::Molecule → molfile → engine → InChI/InChIKey.
+  #
+  # Engines are opt-in: set `AsciiChem::Inchi.engine` (or pass one per
+  # call). Without an engine every derivation raises EngineMissingError
+  # with install guidance — no silent fallback.
+  module Inchi
+    autoload :BinaryEngine, 'asciichem/inchi/binary_engine'
+    autoload :Engine, 'asciichem/inchi/engine'
+    autoload :Identity, 'asciichem/inchi/identity'
+
+    INSTALL_GUIDE = 'install the IUPAC InChI software ' \
+                    '(https://www.inchi-trust.org/downloads/) and set ' \
+                    'AsciiChem::Inchi.engine = AsciiChem::Inchi::BinaryEngine.new ' \
+                    '(or pass bin: "path/to/inchi-1")'
+
+    class << self
+      attr_accessor :engine
+
+      # Derives the identity of one molecule. Falls back to the
+      # configured engine when none is passed; raises
+      # EngineMissingError when neither exists.
+      def identity_for(molecule, engine: nil)
+        selected = engine || self.engine
+        raise EngineMissingError, "no InChI engine configured — #{INSTALL_GUIDE}" if selected.nil?
+
+        selected.identity(molecule)
+      end
+    end
+  end
+end

data/lib/asciichem/linter/identity_cross_check.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Linter
+    # Structural cross-check of identity annotations (TODO.v2 10).
+    # Where IdentifierConsistencyCheck compares offline-analysable
+    # layers (formula composition), this check derives the InChI of
+    # the drawn structure via the configured engine and compares it
+    # to the annotated `@inchi`/`@inchikey` — catching transcription
+    # errors that composition checks cannot (wrong connectivity,
+    # stereo, isotopes).
+    #
+    # Behaviour is engine-scaled, mirroring the resolver's opt-in
+    # sources: with no engine configured the check emits one warning
+    # explaining how to enable it (protection off is worth saying);
+    # with an engine, mismatches are errors. Molecules without
+    # identity annotations are never checked.
+    class IdentityCrossCheck < Base
+      register :identity_cross_check
+
+      def run(formula)
+        annotated = []
+        walk(formula) do |node|
+          next unless node.is_a?(AsciiChem::Model::Molecule)
+
+          annotated << node if identity_annotations?(node)
+        end
+        return [] if annotated.empty?
+
+        engine = AsciiChem::Inchi.engine
+        return [warning(skip_message(annotated.length))] if engine.nil?
+
+        annotated.flat_map { |molecule| cross_check(molecule, engine) }
+      rescue AsciiChem::EngineMissingError => e
+        [warning(e.message)]
+      end
+
+      private
+
+      def identity_annotations?(molecule)
+        molecule.identifiers.any? { |i| %w[inchi inchikey].include?(i.convention.to_s) }
+      end
+
+      def cross_check(molecule, engine)
+        identity = engine.identity(molecule)
+        molecule.identifiers.filter_map do |i|
+          diagnostic_for(i, identity, molecule)
+        end
+      rescue AsciiChem::Error => e
+        # Not derivable (e.g. a formula is not a structure: no bonds)
+        # or the engine rejected it — report, never raise: the linter
+        # stays total.
+        [warning("cannot derive InChI for cross-check: #{e.message}", node: molecule)]
+      end
+
+      def diagnostic_for(identifier, identity, molecule)
+        case identifier.convention.to_s
+        when 'inchi'
+          return nil if identifier.value == identity.inchi
+
+          error('InChI annotation does not match the drawn structure: ' \
+                "annotated #{identifier.value}, computed #{identity.inchi}",
+                node: molecule)
+        when 'inchikey'
+          return nil if identifier.value == identity.inchikey
+
+          error('InChIKey annotation does not match the drawn structure: ' \
+                "annotated #{identifier.value}, computed #{identity.inchikey}",
+                node: molecule)
+        end
+      end
+
+      def skip_message(count)
+        "structural identity cross-check skipped for #{count} annotated molecule(s): " \
+          "no InChI engine configured — #{AsciiChem::Inchi::INSTALL_GUIDE}"
+      end
+    end
+  end
+end

data/lib/asciichem/linter.rb

@@ -18,6 +18,7 @@ module AsciiChem
     autoload :ElementValidationCheck, "asciichem/linter/element_validation_check"
     autoload :IdentifierConsistencyCheck, "asciichem/linter/identifier_consistency_check"
     autoload :IdentifierFormatCheck, "asciichem/linter/identifier_format_check"
+    autoload :IdentityCrossCheck, "asciichem/linter/identity_cross_check"
     autoload :Diagnostic, "asciichem/linter/diagnostic"
     autoload :IsotopeSanityCheck, "asciichem/linter/isotope_sanity_check"
     autoload :Registry, "asciichem/linter/registry"

data/lib/asciichem/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AsciiChem
-  VERSION = "0.26.0"
+  VERSION = "0.28.0"
 end

data/lib/asciichem/wire/core.rb

@@ -63,10 +63,12 @@ module AsciiChem
 
       attribute :nodes, Base, collection: true
       attribute :coefficient, :string
+      attribute :stereo, :string
       attribute :identifiers, Identifier, collection: true
       json do
         map "nodes", to: :nodes
         map "coefficient", to: :coefficient
+        map "stereo", to: :stereo
         map "identifiers", to: :identifiers
       end
     end

data/lib/asciichem/wire_adapter.rb

@@ -136,10 +136,25 @@ module AsciiChem
           type: "molecule",
           nodes: node.nodes.map { |n| to_wire(n) },
           coefficient: node.coefficient,
+          stereo: stereo_to_wire(node.stereo),
           identifiers: node.identifiers.map { |i| identifier_to_wire(i) }
         )
       end
 
+      # Stereo markers cross the wire as the v1 enum strings
+      # ("R", "alpha", ...); the model carries symbols.
+      def stereo_to_wire(stereo)
+        return nil unless stereo
+
+        AsciiChem::Model::Molecule::STEREO_TO_LETTER.fetch(stereo)
+      end
+
+      def stereo_from_wire(stereo)
+        return nil unless stereo
+
+        AsciiChem::Model::Molecule::STEREO_LETTERS.fetch(stereo.to_s)
+      end
+
       def group_to_wire(node)
         AsciiChem::Wire::Group.new(
           type: "group",
@@ -295,6 +310,7 @@ module AsciiChem
         AsciiChem::Model::Molecule.new(
           nodes: Array(wire.nodes).map { |n| from_wire(n) },
           coefficient: wire.coefficient,
+          stereo: stereo_from_wire(wire.stereo),
           identifiers: Array(wire.identifiers).map { |i| identifier_from_wire(i) }
         )
       end

data/lib/asciichem.rb

@@ -15,10 +15,12 @@ module AsciiChem
   autoload :Error, "asciichem/errors"
   autoload :ParseError, "asciichem/errors"
   autoload :FormatError, "asciichem/errors"
+  autoload :EngineMissingError, "asciichem/errors"
   autoload :Formatter, "asciichem/formatter"
   autoload :Grammar, "asciichem/grammar"
   autoload :Greek, "asciichem/greek"
   autoload :Identifiers, "asciichem/identifiers"
+  autoload :Inchi, "asciichem/inchi"
   autoload :Layout, "asciichem/layout"
   autoload :Linter, "asciichem/linter"
   autoload :Model, "asciichem/model"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -57,6 +57,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
+- !ruby/object:Gem::Dependency
+  name: mml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -206,6 +220,10 @@ files:
 - lib/asciichem/identifiers/inchi.rb
 - lib/asciichem/identifiers/inchikey.rb
 - lib/asciichem/identifiers/smiles.rb
+- lib/asciichem/inchi.rb
+- lib/asciichem/inchi/binary_engine.rb
+- lib/asciichem/inchi/engine.rb
+- lib/asciichem/inchi/identity.rb
 - lib/asciichem/layout.rb
 - lib/asciichem/linter.rb
 - lib/asciichem/linter/balance_check.rb
@@ -217,6 +235,7 @@ files:
 - lib/asciichem/linter/element_validation_check.rb
 - lib/asciichem/linter/identifier_consistency_check.rb
 - lib/asciichem/linter/identifier_format_check.rb
+- lib/asciichem/linter/identity_cross_check.rb
 - lib/asciichem/linter/isotope_sanity_check.rb
 - lib/asciichem/linter/registry.rb
 - lib/asciichem/linter/spectrum_peak_check.rb