asciichem 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7748aa7fb152b3dad47ff42c2debe7335af35a2a36c21d2248ff4f5a5231c575
-  data.tar.gz: 4352b4fe40fc6998f9860d155e791d7cf2c4f3cd48f0184696346ba934adaa57
+  metadata.gz: 4602bf349585d9d81483e3561d970efd6bb06f3196d30a0a3017df316699664f
+  data.tar.gz: ea4c38d2af66b75ce2024c5cb1cc866af19584af2edba92b09cc264a7e48037e
 SHA512:
-  metadata.gz: 6a22a8e911ec6a04498285f949f79c1ea5e7e6870d464e3229c3e783e744d151f0506b5200dba58e4e06f23177983dd80b24d172c6d5528e960907da821db64a
-  data.tar.gz: 9d57bab57705518c6f2b40d28f40b0b62c20237d26b9daf20ae4d65bd9b60ad8497ea304c60c163878c412cc6cf61a3c99a6a9179b027bef527e524758b87085
+  metadata.gz: 4dad38021607a88a0f37b90a2320b228d47b6e6197b7102eb48616ea94486ccfc16f953c2c233446ca216eefa1d76aebd0c88b1d40edcb2f582abb56c062e79f
+  data.tar.gz: 4fc1f074a3b182e2d22c263f09044d873a9d96ba1e627e89780e42977a00aedd0e7142590df6aa645e405e7dcbca89076e505abccc3e1e37be99dddfca527372

data/CHANGELOG.md

@@ -3,6 +3,43 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [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
+- The cite syntax (TODO.impl 45): `@cite("pubchem")` on a molecule
+  declares which source to cite it from; `Citation.for_molecule`
+  resolves the molecule's identifiers (registry keys preferred over
+  names) and emits one bibitem per cited source. Zero grammar
+  changes — `@cite` rides the property-annotation form by design.
+
+### Fixed
+- Molecule annotations now canonicalise with spaces between them
+  (`@name("Water") @cas("...")`), matching the TypeScript and Python
+  canonicalisers; Ruby was the outlier joining them without a
+  separator.
+
 ## [0.25.0] - 2026-09-14
 
 ### Added
@@ -435,7 +472,8 @@ This project follows [Semantic Versioning](https://semver.org/).
   `version`.
 - Comprehensive RSpec suite with round-trip conformance.
 
-[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.25.0...HEAD
+[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.26.0...HEAD
+[0.26.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.24.0...v0.25.0
 [0.24.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.22.0...v0.23.0

data/benchmarks/README.md

@@ -41,6 +41,16 @@ as a drop-in speedup for the reference grammar:
    revalidation against the whole corpus with no measured win to
    justify it yet.
 
-**Verdict: not adopted.** Revisit when Parsanol's native backend can
-be engaged for full grammars and shows measured wins on this
-workload; the shim path is a documented no.
+**Verdict: not adopted yet.** Two corrections to the spike (tracked
+upstream in parsanol-ruby#25):
+
+1. The native-DSL micro-benchmark ran in Parsanol's default `:ruby`
+   mode — the Rust core (`:native`) was never engaged, so the native
+   path is unmeasured, not disproven.
+2. The `SO_4^2-` failure is a candidate upstream bug (`repeat` of a
+   `maybe`-prefixed sequence fails at end-of-input; minimal repro in
+   the issue).
+
+Revisit trigger unchanged: engage the native backend for full
+grammars, fix the repetition-termination bug, and beat parslet on
+this workload — then re-run the corpus against the port.

data/lib/asciichem/citation.rb

@@ -81,6 +81,57 @@ module AsciiChem
         bibitem(substance).to_xml
       end
 
+      # The cite syntax (TODO.impl 45): a molecule annotated
+      # `@cite("pubchem")` (a property annotation — the grammar needs
+      # no extension) declares *which source to cite it from*. This
+      # resolves the molecule's identifiers and emits one bibitem per
+      # cited source. Returns [[source, bibitem]] pairs; empty when the
+      # molecule has no @cite annotations.
+      #
+      #   AsciiChem.parse('H_2O @name("water") @cite("pubchem")')
+      #   AsciiChem::Citation.for_molecule(formula.nodes.first).map(&:last)
+      def for_molecule(molecule, cache: nil, fetch: nil)
+        sources = citation_sources(molecule)
+        return [] if sources.empty?
+
+        convention, value = lookup_key(molecule)
+        unless value
+          raise Error,
+                "molecule carries no resolvable identifier for citation " \
+                "(annotate @cas/@inchikey/@smiles or @name)"
+        end
+
+        sources.filter_map do |source|
+          substance = AsciiChem::Resolver[source].new.resolve(
+            value: value, convention: convention, cache: cache, fetch: fetch)
+          next unless substance
+
+          [source, bibitem(substance)]
+        end
+      end
+
+      private
+
+      # The property annotation whose title is "cite": values are the
+      # source names to cite from.
+      def citation_sources(molecule)
+        molecule.properties
+                .select { |p| p.title == "cite" && p.value }
+                .map(&:value)
+      end
+
+      # First identifier the resolver can look up by, in preference
+      # order: unambiguous registry keys before names.
+      def lookup_key(molecule)
+        identifier = molecule.identifiers.find { |i| %w[cas inchikey pubchem-cid].include?(i.convention) }
+        return [identifier.convention, identifier.value] if identifier
+
+        name = molecule.names.first
+        return ["name", name.content] if name
+
+        nil
+      end
+
       private
 
       def title_base(substance)

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

@@ -186,7 +186,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))
@@ -338,25 +338,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/formatter/text.rb

@@ -38,7 +38,7 @@ module AsciiChem
         molecule.labels.each { |l| parts << %(@label("#{l.value}")) if l.value }
         molecule.properties.each { |p| parts << %(@#{p.title}("#{p.value}")) if p.title && p.value }
         molecule.metadata.each { |m| parts << %(@meta("#{m.name}","#{m.content}")) }
-        parts.empty? ? "" : " #{parts.join}"
+        parts.empty? ? "" : " #{parts.join(" ")}"
       end
 
       def visit_atom(atom)

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.25.0"
+  VERSION = "0.27.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.25.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -206,6 +206,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 +221,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