asciichem 0.3.0

data/lib/asciichem/linter/registry.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Linter
+    # Check registry. Each check self-registers at file-load time via
+    # `Registry.add(:name, Klass)`. The registry is a Hash; iteration
+    # order is insertion order.
+    module Registry
+      @checks = []
+
+      class << self
+        def add(name, klass)
+          @checks << [name, klass] unless @checks.any? { |n, _k| n == name }
+        end
+
+        def all
+          @checks.map { |(_name, klass)| klass }
+        end
+
+        def names
+          @checks.map { |(name, _klass)| name }
+        end
+
+        # For testing: clear the registry.
+        def reset
+          @checks.clear
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/linter/unclosed_ring_check.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Linter
+    # Flags ring closure digits that have no matching partner. Catches
+    # typos like `C1-C-C` (digit 1 opened but never closed). Uses
+    # `AsciiChem::RingBonds.unclosed_atoms` as the source of truth.
+    class UnclosedRingCheck < Base
+      register :unclosed_ring
+
+      def run(formula)
+        diagnostics = []
+        walk(formula) do |node|
+          next unless node.is_a?(AsciiChem::Model::Molecule)
+
+          AsciiChem::RingBonds.unclosed_atoms(node).each do |atom|
+            diagnostics << error(
+              "Atom has unmatched ring closure digit(s) #{atom.ring_closures.inspect}",
+              node: atom
+            )
+          end
+        end
+        diagnostics
+      end
+    end
+  end
+end

data/lib/asciichem/linter/valence_check.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Linter
+    # Verifies that each atom's total bond order plus |charge| does not
+    # exceed the element's typical valence. Catches typos like `CH_5`
+    # (carbon with five bonds).
+    #
+    # The valence table lists common valences per element. Unknown
+    # elements produce an info diagnostic, not an error.
+    class ValenceCheck < Base
+      register :valence
+
+      def run(formula)
+        diagnostics = []
+        # Walk molecules so we know which atom is the bonding context.
+        walk(formula) do |node|
+          next unless node.is_a?(AsciiChem::Model::Molecule)
+
+          check_molecule(node, diagnostics)
+        end
+        diagnostics
+      end
+
+      private
+
+      def check_molecule(molecule, diagnostics)
+        # Walk the molecule's nodes; pair each atom with the bonds
+        # immediately adjacent to it in the chain.
+        bond_count = 0
+        molecule.children.each do |node|
+          case node
+          when AsciiChem::Model::Bond
+            bond_count += bond_order(node)
+          when AsciiChem::Model::Atom
+            check_atom(node, bond_count, diagnostics)
+            bond_count = 0
+          when AsciiChem::Model::Group
+            # Group's internal bonds aren't visible here; reset.
+            bond_count = 0
+          end
+        end
+      end
+
+      def bond_order(bond)
+        case bond.kind
+        when :single then 1
+        when :double then 2
+        when :triple then 3
+        when :quadruple then 4
+        else 1
+        end
+      end
+
+      def check_atom(atom, incoming_bond_order, diagnostics)
+        max = AsciiChem::PeriodicTable.max_valence(atom.element)
+        if max.nil?
+          diagnostics << info(
+            "Element #{atom.element.inspect} not in valence table; skipping",
+            node: atom
+          )
+          return
+        end
+
+        # Approximate: an atom with subscript has multiplicity, not
+        # extra bonds. We use incoming_bond_order + |charge| as the
+        # rough load.
+        charge = atom.charge.to_s
+        charge_value = parse_charge_magnitude(charge)
+        load = incoming_bond_order + charge_value
+        return if load <= max
+
+        diagnostics << error(
+          "Atom #{atom.element} has load #{load} (bond order #{incoming_bond_order} + charge #{charge_value}); max valence is #{max}",
+          node: atom
+        )
+      end
+
+      def parse_charge_magnitude(charge)
+        return 0 if charge.nil? || charge.empty?
+
+        match = charge.match(/\A(?<n>\d*)(?<sign>[+-])\z/) ||
+                charge.match(/\A(?<sign>[+-])(?<n>\d*)\z/)
+        return 0 unless match
+
+        n = match[:n].empty? ? 1 : match[:n].to_i
+        n
+      end
+    end
+  end
+end

data/lib/asciichem/linter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Linter framework. The parser is total — it accepts any syntactically
+  # valid input without judging chemistry correctness. The linter is a
+  # separate opt-in pass that walks the model and reports chemistry
+  # errors (unbalanced reactions, valence violations, etc.).
+  #
+  # Checks register themselves via `Linter.register(:name, Klass)`. The
+  # registry is open for extension; adding a new check is a single new
+  # file plus one autoload entry.
+  module Linter
+    autoload :Base, "asciichem/linter/base"
+    autoload :BalanceCheck, "asciichem/linter/balance_check"
+    autoload :BracketBalanceCheck, "asciichem/linter/bracket_balance_check"
+    autoload :ElementValidationCheck, "asciichem/linter/element_validation_check"
+    autoload :Diagnostic, "asciichem/linter/diagnostic"
+    autoload :IsotopeSanityCheck, "asciichem/linter/isotope_sanity_check"
+    autoload :Registry, "asciichem/linter/registry"
+    autoload :UnclosedRingCheck, "asciichem/linter/unclosed_ring_check"
+    autoload :ValenceCheck, "asciichem/linter/valence_check"
+
+    SEVERITIES = %i[error warning info].freeze
+
+    # Run all registered checks against the model. Returns an array of
+    # Diagnostic objects (empty if no issues).
+    def self.run(formula)
+      Registry.all.flat_map { |check| check.new.run(formula) }
+    end
+
+    # Convenience: returns true if any check produced an error.
+    def self.errors?(formula)
+      run(formula).any? { |d| d.severity == :error }
+    end
+
+    # Eagerly trigger every autoload in this module so check files can
+    # self-register. Runs once at module-load time.
+    constants.each { |name| const_get(name) }
+  end
+end

data/lib/asciichem/model/atom.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # A chemical atom: element symbol plus optional isotope, charge,
+    # oxidation state, Lewis markers (lone pairs, radicals), and ring
+    # closure digits.
+    #
+    # The semantic fix over AsciiMath: the prefix isotope (e.g. `^14` in
+    # `^14C`) binds to THIS atom as the `isotope` field, not to a phantom
+    # preceding element. The transform enforces the binding.
+    #
+    # Ring closures (SMILES-style): a digit suffix on an atom opens or
+    # closes a ring. Two atoms with the same digit become bonded.
+    # `C1-C-C-C-C-C1` is cyclohexane. The `ring_closures` field carries
+    # the digit string (e.g. `"1"`); multiple digits mean multiple
+    # open/close points (e.g. `"12"` opens/closes rings 1 and 2).
+    class Atom < Node
+      attr_accessor :element, :isotope, :subscript, :superscript,
+                    :charge, :oxidation_state,
+                    :lone_pairs, :radical_electrons,
+                    :ring_closures,
+                    :x2, :y2, :z2, :atom_parity
+
+      def initialize(element:, isotope: nil, subscript: nil,
+                     superscript: nil, charge: nil, oxidation_state: nil,
+                     lone_pairs: nil, radical_electrons: nil,
+                     ring_closures: nil,
+                     x2: nil, y2: nil, z2: nil, atom_parity: nil)
+        @element = element
+        @isotope = isotope
+        @subscript = subscript
+        @superscript = superscript
+        @charge = charge
+        @oxidation_state = oxidation_state
+        @lone_pairs = lone_pairs
+        @radical_electrons = radical_electrons
+        @ring_closures = ring_closures
+        @x2 = x2
+        @y2 = y2
+        @z2 = z2
+        @atom_parity = atom_parity
+      end
+
+      def value_attributes
+        { element: element, isotope: isotope, subscript: subscript,
+          superscript: superscript, charge: charge,
+          oxidation_state: oxidation_state,
+          lone_pairs: lone_pairs, radical_electrons: radical_electrons,
+          ring_closures: ring_closures,
+          x2: x2, y2: y2, z2: z2, atom_parity: atom_parity }
+      end
+
+      def diagnostic_label
+        "Atom(#{element})"
+      end
+
+      def to_s
+        parts = []
+        parts << ":#{lone_pairs}" if lone_pairs
+        parts << element.to_s
+        parts << "_#{subscript}" if subscript
+        parts << "^#{isotope}" if isotope
+        parts << "^#{superscript}" if superscript
+        parts << "^#{charge}" if charge
+        parts << "^(#{oxidation_state})" if oxidation_state
+        parts << ".#{radical_electrons}" if radical_electrons
+        parts << ring_closures.to_s if ring_closures
+        "Atom(#{parts.join})"
+      end
+    end
+  end
+end

data/lib/asciichem/model/bond.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # A bond between two adjacent nodes in a structural chain.
+    class Bond < Node
+      attr_accessor :kind
+
+      KINDS = {
+        single:    { ascii: "-",  mathml_entity: "-" },
+        double:    { ascii: "=",  mathml_entity: "=" },
+        triple:    { ascii: "#",  mathml_entity: "≡" },
+        quadruple: { ascii: "##", mathml_entity: "≣" },
+        wedge:     { ascii: ">-", mathml_entity: "↑" },
+        hash:      { ascii: "-<", mathml_entity: "↓" },
+        dative:    { ascii: "~>", mathml_entity: "→" },
+        wavy:      { ascii: "~~", mathml_entity: "∼" }
+      }.freeze
+
+      def initialize(kind: :single)
+        @kind = kind
+      end
+
+      def value_attributes
+        { kind: kind }
+      end
+
+      def ascii
+        KINDS.fetch(kind).fetch(:ascii)
+      end
+
+      def entity
+        KINDS.fetch(kind).fetch(:mathml_entity)
+      end
+
+      def to_s
+        "Bond(#{kind})"
+      end
+    end
+  end
+end

data/lib/asciichem/model/electron_configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # Orbital occupancy: `1s^2 2s^2 2p^6`. Each entry is `[orbital,
+    # occupancy]` where orbital is the string label (`"1s"`, `"2p"`) and
+    # occupancy is the electron count as a string.
+    #
+    # Term symbols (^{multiplicity}L_J) live on the optional
+    # `term_symbol` field.
+    class ElectronConfiguration < Node
+      TermSymbol = Struct.new(:multiplicity, :letter, :j_value, keyword_init: true) do
+        def to_s
+          "^#{multiplicity}#{letter}_#{j_value}"
+        end
+      end
+
+      attr_accessor :orbitals, :term_symbol
+
+      def initialize(orbitals:, term_symbol: nil)
+        @orbitals = orbitals
+        @term_symbol = term_symbol
+      end
+
+      def value_attributes
+        { orbitals: orbitals, term_symbol: term_symbol }
+      end
+
+      def to_s
+        parts = orbitals.map { |o, n| "#{o}^#{n}" }
+        parts << term_symbol.to_s if term_symbol
+        "ElectronConfig(#{parts.join(' ')})"
+      end
+    end
+  end
+end

data/lib/asciichem/model/embedded_math.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # A run of mathematics embedded in chemistry. Wraps a
+    # `Plurimath::Math::Formula` so we never reinvent math typography.
+    #
+    # Source spelling: backtick-delimited, e.g. `` `K_c = [P]/[R]` ``.
+    class EmbeddedMath < Node
+      attr_accessor :formula, :source
+
+      def initialize(formula:, source: nil)
+        @formula = formula
+        @source = source
+      end
+
+      def value_attributes
+        { formula: formula, source: source }
+      end
+
+      def to_s
+        "EmbeddedMath(#{source || formula.inspect})"
+      end
+    end
+  end
+end

data/lib/asciichem/model/formula.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # Top-level container: the root of every AsciiChem parse.
+    class Formula < Node
+      attr_accessor :nodes
+
+      def initialize(nodes: [])
+        @nodes = nodes
+      end
+
+      def <<(node)
+        nodes << node
+        self
+      end
+
+      def value_attributes
+        { nodes: nodes }
+      end
+
+      def children
+        nodes
+      end
+
+      def to_s
+        "Formula[#{nodes.map(&:to_s).join(', ')}]"
+      end
+    end
+  end
+end

data/lib/asciichem/model/group.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # A parenthesised sub-formula with an outer multiplicity.
+    class Group < Node
+      attr_accessor :nodes, :multiplicity, :bracket
+
+      def initialize(nodes:, multiplicity: nil, bracket: :paren)
+        @nodes = nodes
+        @multiplicity = multiplicity
+        @bracket = bracket
+      end
+
+      def value_attributes
+        { nodes: nodes, multiplicity: multiplicity, bracket: bracket }
+      end
+
+      def children
+        nodes
+      end
+
+      def to_s
+        open, close = brackets
+        inner = nodes.map(&:to_s).join(", ")
+        suffix = multiplicity ? "_#{multiplicity}" : ""
+        "Group#{open}#{inner}#{close}#{suffix}"
+      end
+
+      def open_char
+        brackets.first
+      end
+
+      def close_char
+        brackets.last
+      end
+
+      private
+
+      def brackets
+        case bracket
+        when :paren  then ["(", ")"]
+        when :square then ["[", "]"]
+        when :brace  then ["{", "}"]
+        else ["(", ")"]
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/model/identifier.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # A molecule identifier. Maps to CML `<identifier>` element.
+    # Carries the identifier value plus `convention` (e.g. "inchi",
+    # "smiles", "cas") and optional `dict_ref`.
+    Identifier = Struct.new(:value, :convention, :dict_ref, keyword_init: true) do
+      def to_s
+        "#{convention}:#{value}"
+      end
+    end
+  end
+end

data/lib/asciichem/model/molecule.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # A molecule: an ordered sequence of atoms/groups with optional
+    # leading stoichiometric coefficient, optional stereochemistry
+    # marker (R/S/E/Z/α/β), and optional names/identifiers for CML
+    # metadata round-trip.
+    class Molecule < Node
+      STEREO_LETTERS = {
+        "R" => :R,
+        "S" => :S,
+        "E" => :E,
+        "Z" => :Z,
+        "a" => :alpha,
+        "alpha" => :alpha,
+        "α" => :alpha,
+        "b" => :beta,
+        "beta" => :beta,
+        "β" => :beta
+      }.freeze
+
+      STEREO_TO_LETTER = {
+        R: "R", S: "S", E: "E", Z: "Z",
+        alpha: "alpha", beta: "beta"
+      }.freeze
+
+      attr_accessor :coefficient, :nodes, :stereo, :names, :identifiers,
+                    :title, :formulas, :properties, :labels, :metadata
+
+      def initialize(nodes:, coefficient: nil, stereo: nil,
+                     names: [], identifiers: [], title: nil,
+                     formulas: [], properties: [], labels: [], metadata: [])
+        @nodes = nodes
+        @coefficient = coefficient
+        @stereo = stereo
+        @names = names
+        @identifiers = identifiers
+        @title = title
+        @formulas = formulas
+        @properties = properties
+        @labels = labels
+        @metadata = metadata
+      end
+
+      def value_attributes
+        { nodes: nodes, coefficient: coefficient, stereo: stereo,
+          names: names, identifiers: identifiers, title: title,
+          formulas: formulas, properties: properties, labels: labels,
+          metadata: metadata }
+      end
+
+      def children
+        nodes
+      end
+
+      def stereo_letter
+        STEREO_TO_LETTER.fetch(stereo) if stereo
+      end
+
+      def to_s
+        prefix = coefficient ? "#{coefficient}" : ""
+        stereo_str = stereo ? "(#{stereo_letter})-" : ""
+        name_str = names.empty? ? "" : " #{names.map(&:to_s).join(', ')}"
+        id_str = identifiers.empty? ? "" : " #{identifiers.map(&:to_s).join(', ')}"
+        "#{stereo_str}#{prefix}Molecule[#{nodes.map(&:to_s).join(', ')}]#{name_str}#{id_str}"
+      end
+    end
+  end
+end

data/lib/asciichem/model/name.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # A molecule name. Maps to CML `<name>` element. Carries the
+    # name content plus optional `convention` and `dict_ref`
+    # attributes for names sourced from dictionaries (IUPAC, CAS,
+    # trivial, etc.).
+    Name = Struct.new(:content, :convention, :dict_ref, keyword_init: true) do
+      def to_s
+        content.to_s
+      end
+    end
+  end
+end

data/lib/asciichem/model/node.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Model
+    # Base class for every model node. Provides:
+    #   - structural equality (class + declared attributes)
+    #   - visitor dispatch (`accept`)
+    #   - convenience formatter shortcuts (`to_mathml`, `to_text`, ...)
+    #
+    # Subclasses declare their comparable attributes by overriding
+    # `value_attributes` (returns a hash of `{ name => value }`). This
+    # avoids reflective instance-variable access and keeps equality
+    # correct as fields are added.
+    class Node
+      def accept(visitor)
+        visitor.public_send(:"visit_#{self.class.short_name}", self)
+      rescue NoMethodError => e
+        raise unless e.name == :"visit_#{self.class.short_name}"
+
+        raise NotImplementedError,
+              "#{visitor.class} does not implement visit_#{self.class.short_name}"
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && value_attributes == other.value_attributes
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, value_attributes].hash
+      end
+
+      def to_mathml
+        AsciiChem::Formatter.render(:mathml, self)
+      end
+
+      def to_text
+        AsciiChem::Formatter.render(:text, self)
+      end
+
+      def to_html
+        AsciiChem::Formatter.render(:html, self)
+      end
+
+      def to_latex
+        AsciiChem::Formatter.render(:latex, self)
+      end
+
+      def to_svg
+        AsciiChem::Formatter.render(:svg, self)
+      end
+
+      def to_cml
+        AsciiChem::Cml.from_asciichem(self)
+      end
+
+      # Subclasses override to expose the attributes that participate in
+      # equality. Default: empty (so two bare Nodes are equal).
+      def value_attributes
+        {}
+      end
+
+      # Child nodes for traversal. Default: no children. Container
+      # classes (Formula, Molecule, Group, Reaction, ReactionCascade)
+      # override to expose their contents; leaves (Atom, Bond,
+      # EmbeddedMath, Text) inherit the empty default.
+      #
+      # Used by Linter::Base#walk. Adding a new container class means
+      # defining `children` on it — no edits to the linter.
+      def children
+        []
+      end
+
+      # Snake-case form of the class basename, used to derive the visitor
+      # method (`Atom` -> `visit_atom`, `ElectronConfiguration` ->
+      # `visit_electron_configuration`). Memoised per class so the
+      # string transformation runs once per class, not once per visit.
+      def self.short_name
+        @short_name ||= begin
+          snake = name.split("::").last
+                      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          snake.downcase
+        end
+      end
+
+      # Human-readable label for linter diagnostics. Default: the
+      # class basename with words separated by spaces
+      # (`"Reaction Cascade"`, `"Electron Configuration"`).
+      # Subclasses with identifying fields override (e.g. `Atom`
+      # includes its element symbol). Keeping this on the model keeps
+      # the linter OCP-clean — adding a new model class means
+      # overriding the method on that class, not editing
+      # `Linter::Diagnostic`'s case statement.
+      def diagnostic_label
+        self.class.short_name.split("_").map(&:capitalize).join(" ")
+      end
+    end
+  end
+end