asciichem 0.5.0 → 0.19.0

data/lib/asciichem/cli.rb

@@ -57,10 +57,12 @@ module AsciiChem
     desc "lint -i INPUT", "Run chemistry checks; exit 1 on error, 0 if clean"
     method_option :input, aliases: "-i", type: :string, required: true,
                            desc: "AsciiChem source text"
+    method_option :format, aliases: "-f", type: :string, default: "text",
+                            desc: "Output format: text or json"
     def lint
       formula = AsciiChem.parse(options[:input])
       diagnostics = AsciiChem::Linter.run(formula)
-      diagnostics.each { |d| puts d }
+      output_lint(diagnostics, options[:format])
       exit diagnostics.any? { |d| d.severity == :error } ? 1 : 0
     rescue AsciiChem::ParseError => e
       warn "Parse error: #{e.message}"
@@ -92,5 +94,25 @@ module AsciiChem
 
       AsciiChem::Formatter.render(format.to_sym, formula)
     end
+
+    def output_lint(diagnostics, format)
+      case format.to_s
+      when "json" then output_lint_json(diagnostics)
+      else
+        diagnostics.each { |d| puts d }
+      end
+    end
+
+    def output_lint_json(diagnostics)
+      require "json"
+      payload = diagnostics.map do |d|
+        {
+          severity: d.severity.to_s,
+          message: d.message,
+          node: d.node&.diagnostic_label
+        }
+      end
+      puts JSON.pretty_generate(payload)
+    end
   end
 end

data/lib/asciichem/cml/conditions_extensions.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module AsciiChem
+  module Cml
+    # Carries per-reaction conditions (above/below the arrow) through
+    # CML round-trip. v0.11.0+: chemicalml 0.3.0 Reaction wire now
+    # serialises `<conditionList>` natively, so conditions are emitted
+    # by the adapter directly. This module now handles ONLY:
+    #
+    # - Parse legacy `<conditionList>` from XML (for files written by
+    #   other CML tools or older AsciiChem versions using aci: attrs)
+    # - Parse legacy `aci:conditionsAbove`/`aci:conditionsBelow`
+    #   attributes for backwards compat
+    #
+    # The inject path is retained only to support test fixtures that
+    # build XML by hand; production emit goes through the adapter.
+    module ConditionsExtensions
+      # Inject aci:conditionsAbove/Below attributes for legacy consumers.
+      # v0.11.0+: native <conditionList> is emitted by the adapter, so
+      # this is now suppressed unless conditions are missing from the
+      # XML (defensive — shouldn't normally trigger).
+      def self.inject(xml, formula)
+        conditions_map = build_conditions_map(formula)
+        return xml if conditions_map.empty?
+
+        # If native <conditionList> already present, skip aci: emit.
+        doc_check = Nokogiri::XML(xml)
+        return xml if doc_check.xpath('//cml:reaction/cml:conditionList',
+                                      cml: Extensions::CML_NS).any?
+
+        doc = Nokogiri::XML(xml)
+        root = doc.root
+        Extensions.ensure_namespace(root)
+        apply_conditions(root, conditions_map)
+        doc.to_xml
+      end
+
+      # Extract aci:conditionsAbove/Below from each <reaction>.
+      # Returns `{ reaction_id => { above:, below: } }`.
+      def self.extract(xml)
+        doc = Nokogiri::XML(xml)
+        result = {}
+        doc.xpath('//cml:reaction', cml: Extensions::CML_NS).each do |el|
+          id = el['id']
+          next unless id
+
+          above = el["#{Extensions::PREFIX}:conditionsAbove"]
+          below = el["#{Extensions::PREFIX}:conditionsBelow"]
+          result[id] = { above: above, below: below } if above || below
+        end
+        result
+      end
+
+      # Restore extracted conditions onto matching reactions in a
+      # freshly-parsed formula. Walks in canonical order to match IDs.
+      def self.restore(formula, conditions_map)
+        return formula if conditions_map.empty?
+
+        prefix = AsciiChem::Cml::ID_PREFIXES.fetch(:reaction)
+        index = 0
+        each_reaction_in_canonical_order(formula) do |reaction|
+          index += 1
+          data = conditions_map["#{prefix}#{index}"]
+          next unless data
+
+          reaction.conditions = AsciiChem::Model::Reaction::Conditions.new(
+            above: data[:above],
+            below: data[:below]
+          )
+        end
+        formula
+      end
+
+      class << self
+        private
+
+        def build_conditions_map(formula)
+          prefix = AsciiChem::Cml::ID_PREFIXES.fetch(:reaction)
+          index = 0
+          map = {}
+          each_reaction_in_canonical_order(formula) do |reaction|
+            index += 1
+            next unless reaction.conditions
+
+            data = conditions_data(reaction)
+            map["#{prefix}#{index}"] = data if data[:above] || data[:below]
+          end
+          map
+        end
+
+        def conditions_data(reaction)
+          {
+            above: reaction.conditions&.above,
+            below: reaction.conditions&.below
+          }
+        end
+
+        def each_reaction_in_canonical_order(formula, &block)
+          formula.nodes.each do |node|
+            case node
+            when AsciiChem::Model::Reaction
+              yield node
+            when AsciiChem::Model::ReactionCascade
+              node.steps.each(&block)
+            end
+          end
+        end
+
+        def apply_conditions(root, conditions_map)
+          conditions_map.each do |reaction_id, data|
+            reaction_el = root.at_xpath(
+              "//cml:reaction[@id='#{reaction_id}']",
+              cml: Extensions::CML_NS
+            )
+            next unless reaction_el
+
+            apply_one_condition(reaction_el, data)
+          end
+        end
+
+        def apply_one_condition(reaction_el, data)
+          reaction_el["#{Extensions::PREFIX}:conditionsAbove"] = data[:above] if data[:above]
+          return unless data[:below]
+
+          reaction_el["#{Extensions::PREFIX}:conditionsBelow"] = data[:below]
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/cml/extensions/atom_attributes.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module AsciiChem
+  module Cml
+    module Extensions
+      # Atom-attribute extension channel: carries per-atom fields that
+      # CML's standard wire format doesn't cover (oxidation state, lone
+      # pairs, radical electrons, ring closures, atom parity) via
+      # `aci:<wire_name>` attributes on `<atom>` elements.
+      #
+      # CML tools that don't recognise the aci: namespace ignore these
+      # attributes — schema validity is preserved.
+      module AtomAttributes
+        # Map of AsciiChem::Model::Atom attribute name (Symbol) to the
+        # wire attribute name (without prefix). Each entry produces a
+        # corresponding `aci:<wire_name>` attribute in the CML output.
+        FIELDS = {
+          oxidation_state: 'oxidationState',
+          lone_pairs: 'lonePairs',
+          radical_electrons: 'radicalElectrons',
+          ring_closures: 'ringClosures',
+          atom_parity: 'atomParity'
+        }.freeze
+
+        # Build the extensions map: `{ atom_id => { field: value } }`.
+        # Values are Ruby-native (Integer for counts, String for
+        # oxidation state). Atoms without extension data are omitted.
+        def self.collect(atom_mapping)
+          atom_mapping.each_with_object({}) do |(atom_id, source_atom), memo|
+            data = build_entry(source_atom)
+            memo[atom_id] = data unless data.empty?
+          end
+        end
+
+        # Inject aci: attributes into a CML XML string. Returns the
+        # modified XML. No-op if the extensions map is empty.
+        def self.inject(xml, extensions)
+          return xml if extensions.empty?
+
+          doc = Nokogiri::XML(xml)
+          root = doc.root
+          unless root.namespaces.value?(Extensions::NAMESPACE)
+            root.add_namespace(Extensions::PREFIX, Extensions::NAMESPACE)
+          end
+
+          extensions.each do |atom_id, entry|
+            atom_el = root.at_xpath("//cml:atom[@id='#{atom_id}']",
+                                    cml: Extensions::CML_NS)
+            next unless atom_el
+
+            entry.each do |attr_name, value|
+              wire_name = FIELDS.fetch(attr_name)
+              atom_el["#{Extensions::PREFIX}:#{wire_name}"] = value.to_s
+            end
+          end
+
+          doc.to_xml
+        end
+
+        # Extract aci: attributes from a CML XML string. Returns a map
+        # `{ atom_id => { field: value } }` with Ruby-native types.
+        def self.extract(xml)
+          doc = Nokogiri::XML(xml)
+          result = {}
+          doc.xpath('//cml:atom', cml: Extensions::CML_NS).each do |atom_el|
+            atom_id = atom_el['id']
+            next unless atom_id
+
+            entry = read_entry(atom_el)
+            result[atom_id] = entry unless entry.empty?
+          end
+          result
+        end
+
+        # Apply extracted extension data to a freshly-parsed formula.
+        # Atoms are walked in parallel between the canonical document
+        # (which has IDs) and the formula (which has model objects).
+        def self.restore(formula, canonical_doc, extensions)
+          return formula if extensions.empty?
+
+          canonical_atoms = flatten_canonical_atoms(canonical_doc)
+          formula_atoms = flatten_formula_atoms(formula)
+
+          canonical_atoms.each_with_index do |canon_atom, idx|
+            entry = extensions[canon_atom.id]
+            next unless entry
+
+            target = formula_atoms[idx]
+            next unless target
+
+            apply_entry(target, entry)
+          end
+          formula
+        end
+
+        class << self
+          private
+
+          def build_entry(atom)
+            FIELDS.each_with_object({}) do |(attr_name, _wire_name), entry|
+              value = atom.public_send(attr_name)
+              entry[attr_name] = value if value
+            end
+          end
+
+          def read_entry(atom_el)
+            FIELDS.each_with_object({}) do |(attr_name, wire_name), entry|
+              value = atom_el["#{Extensions::PREFIX}:#{wire_name}"]
+              entry[attr_name] = cast_from_xml(attr_name, value) if value
+            end
+          end
+
+          # Cast an XML string back to its Ruby form. Integer counts
+          # become Integers; everything else stays a string.
+          def cast_from_xml(attr_name, value)
+            case attr_name
+            when :lone_pairs, :radical_electrons then value.to_i
+            else value
+            end
+          end
+
+          def apply_entry(atom, entry)
+            entry.each do |attr_name, value|
+              atom.public_send(:"#{attr_name}=", value)
+            end
+          end
+
+          # Flatten the canonical document's atoms in the order
+          # ToCanonical walked them: top-level molecules, then reaction
+          # reactants+products, then cascade reactions.
+          def flatten_canonical_atoms(canonical_doc)
+            atoms = []
+            canonical_doc.molecules.each { |m| atoms.concat((m.atom_array&.atoms || [])) }
+            canonical_doc.reactions.each do |reaction|
+              atoms.concat(flatten_reaction_atoms(reaction))
+            end
+            canonical_doc.reaction_lists.each do |list|
+              list.reactions.each { |r| atoms.concat(flatten_reaction_atoms(r)) }
+            end
+            atoms
+          end
+
+          def flatten_reaction_atoms(reaction)
+            atoms = []
+            reactants = reaction.reactant_list
+            products = reaction.product_list
+            reactants&.reactants&.each { |r| atoms.concat(r.substance.molecule.atom_array&.atoms || []) }
+            products&.products&.each { |p| atoms.concat(p.substance.molecule.atom_array&.atoms || []) }
+            atoms
+          end
+
+          # Flatten the AsciiChem::Model::Formula's atoms in the same
+          # order ToCanonical walks them. Matches
+          # flatten_canonical_atoms one-for-one so parallel iteration
+          # by index works.
+          def flatten_formula_atoms(formula)
+            formula.nodes.each_with_object([]) do |node, memo|
+              case node
+              when AsciiChem::Model::Molecule
+                memo.concat(flatten_molecule_atoms(node))
+              when AsciiChem::Model::Reaction
+                memo.concat(reaction_atoms(node))
+              when AsciiChem::Model::ReactionCascade
+                node.steps.each { |step| memo.concat(reaction_atoms(step)) }
+              end
+            end
+          end
+
+          def reaction_atoms(reaction)
+            atoms = []
+            reaction.reactants.each { |m| atoms.concat(flatten_molecule_atoms(m)) }
+            reaction.products.each { |m| atoms.concat(flatten_molecule_atoms(m)) }
+            atoms
+          end
+
+          def flatten_molecule_atoms(molecule)
+            molecule.nodes.each_with_object([]) do |node, memo|
+              case node
+              when AsciiChem::Model::Atom
+                memo << node
+              when AsciiChem::Model::Group, AsciiChem::Model::Molecule
+                memo.concat(flatten_molecule_atoms(node))
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/cml/extensions/top_level.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'set'
+
+module AsciiChem
+  module Cml
+    module Extensions
+      # Top-level construct extension channel: carries AsciiChem model
+      # classes that have no CML wire equivalent (ElectronConfiguration,
+      # EmbeddedMath, Text, Crystal, Spectrum, Calculation, ZMatrix,
+      # Mechanism) as `aci:<element_name>` children of `<cml>`.
+      #
+      # Position in the original formula's node list is preserved via a
+      # `position` attribute so restore can re-insert at the right index.
+      # The wire format for each handler is the AsciiChem text rendering
+      # — round-trip-safe by construction (Text formatter is the
+      # canonicaliser).
+      module TopLevel
+        # Registry of handlers. Each is a Struct with `node_class`,
+        # `element_name`, `serialize`, `deserialize`. Adding a new
+        # top-level extension is one factory call.
+        #
+        # Factory methods on the struct eliminate the duplicated
+        # serialize/deserialize lambdas. A construct needing bespoke
+        # logic calls `.new(...)` directly with custom lambdas.
+        # Registry entry mapping a model class to its aci: wire element.
+        # Construct via the factory methods (.text_round_trip,
+        # .source_with_wrapper) instead of .new where possible.
+        Handler = Struct.new(:node_class, :element_name,
+                             :serialize, :deserialize, keyword_init: true)
+
+        class Handler
+          # Default pattern: serialize via Text formatter, deserialize
+          # by re-parsing. Round-trip-safe by construction.
+          def self.text_round_trip(node_class:, element_name:)
+            new(
+              node_class: node_class,
+              element_name: element_name,
+              serialize: ->(node) { AsciiChem::Formatter.render(:text, node) },
+              deserialize: ->(content) { AsciiChem.parse(content).nodes.first }
+            )
+          end
+
+          # Pattern for constructs whose text format wraps content in
+          # delimiter chars (e.g. EmbeddedMath wraps in backticks) and
+          # whose model carries the unwrapped form in `source`.
+          def self.source_with_wrapper(node_class:, element_name:, wrapper:)
+            new(
+              node_class: node_class,
+              element_name: element_name,
+              serialize: ->(node) { node.source.to_s },
+              deserialize: ->(content) { AsciiChem.parse("#{wrapper}#{content}#{wrapper}").nodes.first }
+            )
+          end
+        end
+
+        HANDLERS = [
+          Handler.text_round_trip(
+            node_class: AsciiChem::Model::ElectronConfiguration,
+            element_name: 'electronConfiguration'
+          ),
+          Handler.source_with_wrapper(
+            node_class: AsciiChem::Model::EmbeddedMath,
+            element_name: 'embeddedMath',
+            wrapper: '`'
+          ),
+          Handler.text_round_trip(
+            node_class: AsciiChem::Model::Text,
+            element_name: 'text'
+          ),
+          # Beyond-formulas constructs — each carries its text rendering
+          # inside an aci: element. On parse, the text is re-parsed.
+          Handler.text_round_trip(
+            node_class: AsciiChem::Model::Crystal,
+            element_name: 'crystal'
+          ),
+          Handler.text_round_trip(
+            node_class: AsciiChem::Model::Spectrum,
+            element_name: 'spectrum'
+          ),
+          Handler.text_round_trip(
+            node_class: AsciiChem::Model::Calculation,
+            element_name: 'calculation'
+          ),
+          Handler.text_round_trip(
+            node_class: AsciiChem::Model::ZMatrix,
+            element_name: 'zmatrix'
+          ),
+          Handler.text_round_trip(
+            node_class: AsciiChem::Model::Mechanism,
+            element_name: 'mechanism'
+          )
+        ].freeze
+
+        # Build the top-level extensions list from a formula. Returns
+        # an array of `{ position:, element_name:, content: }` hashes.
+        # Pass `skip_classes:` to suppress the aci: text carrier for
+        # constructs that have native wire representation elsewhere
+        # in the pipeline (e.g. Crystal via chemicalml 0.3.0).
+        def self.collect(formula, skip_classes: [])
+          handlers_by_class = HANDLERS.to_h { |h| [h.node_class, h] }
+          skip_set = skip_classes.to_set
+          formula.nodes.each_with_index.with_object([]) do |(node, idx), memo|
+            next if skip_set.include?(node.class)
+
+            handler = handlers_by_class[node.class]
+            next unless handler
+
+            memo << {
+              position: idx,
+              element_name: handler.element_name,
+              content: handler.serialize.call(node)
+            }
+          end
+        end
+
+        # Inject top-level extensions into CML XML as `aci:` elements
+        # inside `<cml>`. No-op if the list is empty.
+        def self.inject(xml, top_level)
+          return xml if top_level.empty?
+
+          doc = Nokogiri::XML(xml)
+          root = doc.root
+          unless root.namespaces.value?(Extensions::NAMESPACE)
+            root.add_namespace(Extensions::PREFIX, Extensions::NAMESPACE)
+          end
+          top_level.each { |entry| insert_element(doc, root, entry) }
+          doc.to_xml
+        end
+
+        # Extract `aci:` top-level elements from CML XML. Returns an
+        # array of `{ position:, element_name:, content: }` hashes in
+        # ascending position order.
+        def self.extract(xml)
+          doc = Nokogiri::XML(xml)
+          result = []
+          element_names = HANDLERS.map(&:element_name)
+          element_names.each do |name|
+            doc.xpath("//#{Extensions::PREFIX}:#{name}",
+                      Extensions::PREFIX => Extensions::NAMESPACE).each do |el|
+              result << {
+                position: (el['position'] || 0).to_i,
+                element_name: name,
+                content: el.content
+              }
+            end
+          end
+          result.sort_by { |entry| entry[:position] }
+        end
+
+        # Restore top-level extension nodes into a freshly-parsed
+        # formula. Inserts each node at its original position; nodes
+        # are inserted in ascending position order so earlier inserts
+        # don't shift later positions.
+        def self.restore(formula, top_level)
+          handlers_by_element = HANDLERS.to_h { |h| [h.element_name, h] }
+          top_level.sort_by { |entry| entry[:position] }.each do |entry|
+            handler = handlers_by_element[entry[:element_name]]
+            next unless handler
+
+            node = handler.deserialize.call(entry[:content])
+            next unless node
+
+            pos = [entry[:position], formula.nodes.length].min
+            formula.nodes.insert(pos, node)
+          end
+          formula
+        end
+
+        class << self
+          private
+
+          def insert_element(doc, root, entry)
+            element = doc.create_element("#{Extensions::PREFIX}:#{entry[:element_name]}")
+            element['position'] = entry[:position].to_s
+            element.content = entry[:content]
+            # Insert before existing children so extensions appear at
+            # the top of <cml>, which reads more naturally than appended.
+            root.children.first&.add_previous_sibling(element) || root.add_child(element)
+          end
+        end
+      end
+    end
+  end
+end