asciichem 0.3.0

data/lib/asciichem/greek.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # AsciiMath-style Greek word → Unicode symbol table. Used by the
+  # grammar and transform to accept typed Greek words (`alpha`, `Delta`,
+  # etc.) alongside Unicode characters (`α`, `Δ`).
+  #
+  # Single source of truth — the stereo grammar, the conditions
+  # translator, and any future site that needs Greek letters all read
+  # from this hash. Adding a new word is one entry here, not edits
+  # scattered across the grammar.
+  module Greek
+    LOWERCASE = {
+      "alpha"   => "α",
+      "beta"    => "β",
+      "gamma"   => "γ",
+      "delta"   => "δ",
+      "epsilon" => "ε",
+      "zeta"    => "ζ",
+      "eta"     => "η",
+      "theta"   => "θ",
+      "iota"    => "ι",
+      "kappa"   => "κ",
+      "lambda"  => "λ",
+      "mu"      => "μ",
+      "nu"      => "ν",
+      "xi"      => "ξ",
+      "omicron" => "ο",
+      "pi"      => "π",
+      "rho"     => "ρ",
+      "sigma"   => "σ",
+      "tau"     => "τ",
+      "upsilon" => "υ",
+      "phi"     => "φ",
+      "chi"     => "χ",
+      "psi"     => "ψ",
+      "omega"   => "ω"
+    }.freeze
+
+    UPPERCASE = {
+      "Alpha"   => "Α",
+      "Beta"    => "Β",
+      "Gamma"   => "Γ",
+      "Delta"   => "Δ",
+      "Epsilon" => "Ε",
+      "Zeta"    => "Ζ",
+      "Eta"     => "Η",
+      "Theta"   => "Θ",
+      "Iota"    => "Ι",
+      "Kappa"   => "Κ",
+      "Lambda"  => "Λ",
+      "Mu"      => "Μ",
+      "Nu"      => "Ν",
+      "Xi"      => "Ξ",
+      "Omicron" => "Ο",
+      "Pi"      => "Π",
+      "Rho"     => "Ρ",
+      "Sigma"   => "Σ",
+      "Tau"     => "Τ",
+      "Upsilon" => "Υ",
+      "Phi"     => "Φ",
+      "Chi"     => "Χ",
+      "Psi"     => "Ψ",
+      "Omega"   => "Ω"
+    }.freeze
+
+    ALL = LOWERCASE.merge(UPPERCASE).freeze
+
+    # Translate every Greek word in `text` to its Unicode symbol.
+    # Non-word substrings pass through unchanged. Longest-word-first
+    # so "eta" doesn't shadow "beta" (which contains "eta" as a suffix).
+    def self.translate(text)
+      return text if text.nil? || text.empty?
+
+      sorted_words = ALL.keys.sort_by(&:length).reverse
+      pattern = /#{sorted_words.map { |w| Regexp.escape(w) }.join("|")}/
+      text.gsub(pattern) { |match| ALL.fetch(match) }
+    end
+  end
+end

data/lib/asciichem/layout.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require 'elkrb'
+
+module AsciiChem
+  # 2D structural layout for molecules. Walks an
+  # `AsciiChem::Model::Molecule`, builds an elkrb graph (atoms as
+  # nodes, bonds as edges), runs a layout algorithm, and returns a
+  # `Layout::Result` ready for SVG rendering.
+  #
+  # Three concerns, MECE:
+  #
+  # - `MoleculeWalker` — walks the AsciiChem tree, assigns stable IDs,
+  #   produces a neutral atom+bond list. Knows nothing about elkrb.
+  # - `GraphBuilder` — converts the walker's neutral list into an
+  #   elkrb graph. Knows nothing about AsciiChem::Model.
+  # - `ResultExtractor` — maps elkrb's laid-out positions back onto
+  #   the walker's neutral list, producing a `Layout::Result`.
+  #
+  # Each is independently testable. New algorithms (ring detection,
+  # stereo placement) slot in as additional visitors over the same
+  # `Layout::Result`; no edits to the walker or extractor.
+  module Layout
+    ATOM_WIDTH  = 40.0
+    ATOM_HEIGHT = 30.0
+    PADDING     = 20.0
+
+    PositionedAtom = Struct.new(:id, :element, :x, :y, :charge, :isotope,
+                                :multiplicity, keyword_init: true)
+    PositionedBond = Struct.new(:id, :kind, :from_id, :to_id, keyword_init: true)
+
+    # Layout result: positioned atoms and bonds ready for rendering.
+    Result = Struct.new(:atoms, :bonds, :width, :height, keyword_init: true) do
+      def atoms_by_id
+        @atoms_by_id ||= atoms.to_h { |a| [a.id, a] }
+      end
+
+      def empty?
+        atoms.empty?
+      end
+    end
+
+    # Empty result returned when layout is not applicable (e.g.
+    # molecule has no atoms). Keeps callers from special-casing nil.
+    def self.empty_result
+      Result.new(atoms: [], bonds: [], width: 0.0, height: 0.0)
+    end
+
+    # Compute 2D positions for a molecule's atoms and bonds.
+    # Returns a `Layout::Result`. Algorithm defaults to `layered`
+    # (Sugiyama-style hierarchical) which is deterministic across
+    # runs — essential for visual regression testing. Pass
+    # `algorithm: "force"` for organic-looking layouts, with the
+    # caveat that output may vary between runs.
+    def self.layout(molecule, algorithm: 'layered')
+      walker = MoleculeWalker.new(molecule)
+      walk = walker.walk
+      return empty_result if walk.atoms.empty?
+
+      # If all atoms carry pre-positioned coordinates (e.g. from CML
+      # x2/y2 attributes), skip elkrb and use the provided positions
+      # directly. This preserves the molecule's original geometry when
+      # round-tripping through CML.
+      return pre_positioned_result(walk) if all_positioned?(walk)
+
+      graph = GraphBuilder.new(walk).build(algorithm: algorithm)
+      laid_out = Elkrb.layout(graph, algorithm: algorithm)
+      ResultExtractor.new(laid_out, walk).extract
+    end
+
+    def self.all_positioned?(walk)
+      walk.atoms.any? && walk.atoms.all? { |a| a.x2 && a.y2 }
+    end
+    private_class_method :all_positioned?
+
+    # Build a Layout::Result directly from WalkAtoms that already
+    # carry x2/y2 coordinates. No elkrb involved.
+    def self.pre_positioned_result(walk)
+      atoms = walk.atoms.map do |wa|
+        PositionedAtom.new(
+          id: wa.id,
+          element: wa.element,
+          x: wa.x2.to_f,
+          y: wa.y2.to_f,
+          charge: wa.charge,
+          isotope: wa.isotope,
+          multiplicity: wa.multiplicity
+        )
+      end
+      bonds = walk.bonds.map do |wb|
+        PositionedBond.new(id: wb.id, kind: wb.kind,
+                           from_id: wb.from_id, to_id: wb.to_id)
+      end
+      max_x = atoms.map(&:x).max || 0.0
+      max_y = atoms.map(&:y).max || 0.0
+      Result.new(atoms: atoms, bonds: bonds,
+                 width: max_x + PADDING,
+                 height: max_y + PADDING)
+    end
+    private_class_method :pre_positioned_result
+
+    # Walks an AsciiChem::Model::Molecule in source order, assigning
+    # deterministic IDs and emitting atoms + bonds. Pure; no elkrb
+    # dependency.
+    class MoleculeWalker
+      attr_reader :atoms, :bonds
+
+      def initialize(molecule)
+        @molecule = molecule
+        @atoms = []
+        @bonds = []
+        @atom_counter = IdCounter.new('a')
+        @bond_counter = IdCounter.new('b')
+        @pending_bond = nil
+        @last_atom_id = nil
+        @atom_id_by_object_id = {}
+      end
+
+      # Returns a WalkResult — the neutral atom+bond list with
+      # element/charge/etc preserved from the source molecule.
+      def walk
+        walk_nodes(@molecule.nodes)
+        emit_ring_bonds
+        WalkResult.new(atoms: @atoms, bonds: @bonds)
+      end
+
+      # Emit a bond for each ring-closure pair. Uses
+      # `AsciiChem::RingBonds.each_in` so the algorithm is shared
+      # with the CML adapter and the linter.
+      def emit_ring_bonds
+        AsciiChem::RingBonds.each_in(@molecule) do |ring_bond|
+          from_id = @atom_id_by_object_id[ring_bond.from_atom.object_id]
+          to_id = @atom_id_by_object_id[ring_bond.to_atom.object_id]
+          next unless from_id && to_id
+
+          @bonds << WalkBond.new(
+            id: @bond_counter.next,
+            kind: :single,
+            from_id: from_id,
+            to_id: to_id
+          )
+        end
+      end
+
+      private
+
+      def walk_nodes(nodes)
+        nodes.each do |node|
+          case node
+          when AsciiChem::Model::Atom
+            emit_atom(node)
+          when AsciiChem::Model::Bond
+            @pending_bond = node
+          when AsciiChem::Model::Group, AsciiChem::Model::Molecule
+            walk_nodes(node.nodes)
+          end
+        end
+      end
+
+      def emit_atom(atom)
+        id = @atom_counter.next
+        @atom_id_by_object_id[atom.object_id] = id
+        @atoms << WalkAtom.new(
+          id: id,
+          element: atom.element,
+          charge: atom.charge,
+          isotope: atom.isotope,
+          multiplicity: atom.subscript,
+          x2: atom.x2,
+          y2: atom.y2
+        )
+        emit_pending_bond(id) if @pending_bond && @last_atom_id
+        @last_atom_id = id
+        @pending_bond = nil
+      end
+
+      def emit_pending_bond(next_atom_id)
+        @bonds << WalkBond.new(
+          id: @bond_counter.next,
+          kind: @pending_bond.kind,
+          from_id: @last_atom_id,
+          to_id: next_atom_id
+        )
+      end
+    end
+    private_constant :MoleculeWalker
+
+    # Neutral walker output. Decouples the walker from both elkrb and
+    # the canonical model — the same walk could feed any future
+    # graph-based renderer.
+    WalkAtom = Struct.new(:id, :element, :charge, :isotope, :multiplicity, :x2, :y2, keyword_init: true)
+    WalkBond = Struct.new(:id, :kind, :from_id, :to_id, keyword_init: true)
+    WalkResult = Struct.new(:atoms, :bonds, keyword_init: true)
+    private_constant :WalkAtom, :WalkBond, :WalkResult
+
+    # Builds an elkrb graph from a walker's neutral output. Knows
+    # only about elkrb's Node/Edge/Graph classes and the Layout
+    # dimension constants.
+    class GraphBuilder
+      def initialize(walk)
+        @walk = walk
+      end
+
+      def build(algorithm:)
+        children = @walk.atoms.map { |a| elkrb_node(a) }
+        edges = @walk.bonds.map { |b| elkrb_edge(b) }
+        Elkrb::Graph::Graph.new(
+          id: 'root',
+          children: children,
+          edges: edges,
+          layout_options: Elkrb::Graph::LayoutOptions.new(algorithm: algorithm)
+        )
+      end
+
+      private
+
+      def elkrb_node(atom)
+        Elkrb::Graph::Node.new(
+          id: atom.id,
+          width: Layout::ATOM_WIDTH,
+          height: Layout::ATOM_HEIGHT,
+          properties: { 'element' => atom.element,
+                        'charge' => atom.charge,
+                        'isotope' => atom.isotope,
+                        'multiplicity' => atom.multiplicity }
+        )
+      end
+
+      def elkrb_edge(bond)
+        Elkrb::Graph::Edge.new(
+          id: bond.id,
+          sources: [bond.from_id],
+          targets: [bond.to_id],
+          properties: { 'kind' => bond.kind.to_s }
+        )
+      end
+    end
+    private_constant :GraphBuilder
+
+    # Maps an elkrb laid-out graph back onto the walker's neutral
+    # atom+bond list, producing a `Layout::Result`. Positions come
+    # from elkrb; everything else (element, charge, kind) comes from
+    # the walker — elkrb doesn't carry chemistry semantics.
+    class ResultExtractor
+      def initialize(laid_out, walk)
+        @laid_out = laid_out
+        @walk = walk
+      end
+
+      def extract
+        position_by_id = build_position_map
+        atoms = build_positioned_atoms(position_by_id)
+        bonds = build_positioned_bonds
+        Layout::Result.new(
+          atoms: atoms,
+          bonds: bonds,
+          width: @laid_out.width.to_f + Layout::PADDING,
+          height: @laid_out.height.to_f + Layout::PADDING
+        )
+      end
+
+      private
+
+      def build_position_map
+        @laid_out.children.to_h do |node|
+          [node.id, [node.x.to_f, node.y.to_f]]
+        end
+      end
+
+      def build_positioned_atoms(position_by_id)
+        @walk.atoms.map do |walk_atom|
+          x, y = position_by_id.fetch(walk_atom.id, [0.0, 0.0])
+          Layout::PositionedAtom.new(
+            id: walk_atom.id,
+            element: walk_atom.element,
+            x: x,
+            y: y,
+            charge: walk_atom.charge,
+            isotope: walk_atom.isotope,
+            multiplicity: walk_atom.multiplicity
+          )
+        end
+      end
+
+      def build_positioned_bonds
+        @walk.bonds.map do |walk_bond|
+          Layout::PositionedBond.new(
+            id: walk_bond.id,
+            kind: walk_bond.kind,
+            from_id: walk_bond.from_id,
+            to_id: walk_bond.to_id
+          )
+        end
+      end
+    end
+    private_constant :ResultExtractor
+
+    # Per-build ID counter. Format: `prefix + N` (e.g. "a1", "b2").
+    # Walker instances are per-translation so IDs reset cleanly.
+    class IdCounter
+      def initialize(prefix)
+        @prefix = prefix
+        @counter = 0
+      end
+
+      def next
+        @counter += 1
+        "#{@prefix}#{@counter}"
+      end
+    end
+    private_constant :IdCounter
+  end
+end

data/lib/asciichem/linter/balance_check.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Linter
+    # Verifies that a reaction is stoichiometrically balanced — the
+    # atom counts on the reactants side equal those on the products
+    # side. Coefficients and group multiplicities are applied.
+    #
+    # The check ignores electrons (`e^-`), conditions, and the arrow
+    # kind. It treats unknown constructs conservatively: any molecule
+    # it can't enumerate atoms for is skipped, not flagged.
+    class BalanceCheck < Base
+      register :balance
+
+      def run(formula)
+        diagnostics = []
+        walk(formula) do |node|
+          next unless node.is_a?(AsciiChem::Model::Reaction)
+
+          check_reaction(node, diagnostics)
+        end
+        diagnostics
+      end
+
+      private
+
+      def check_reaction(reaction, diagnostics)
+        reactants = count_side(reaction.reactants)
+        products = count_side(reaction.products)
+        return if reactants.nil? || products.nil?
+        return if reactants == products
+
+        diffs = compute_diffs(reactants, products)
+        diagnostics << error(
+          "Reaction is not balanced: #{diffs}",
+          node: reaction
+        )
+      end
+
+      # Returns a Hash mapping element symbol to count, or nil if any
+      # molecule on the side couldn't be enumerated.
+      def count_side(molecules)
+        counts = Hash.new(0)
+        molecules.each do |molecule|
+          mol_counts = count_molecule(molecule)
+          return nil if mol_counts.nil?
+
+          mol_counts.each { |element, n| counts[element] += n }
+        end
+        counts
+      end
+
+      def count_molecule(molecule)
+        coefficient = molecule.coefficient.to_i
+        coefficient = 1 if coefficient.zero?
+        raw = enumerate(molecule, 1)
+        return nil if raw.nil?
+
+        raw.transform_values { |v| v * coefficient }
+      end
+
+      # Recursive enumeration with a current multiplier.
+      def enumerate(node, multiplier)
+        case node
+        when AsciiChem::Model::Atom
+          sub = (node.subscript || "1").to_i
+          sub = 1 if sub.zero?
+          { node.element => sub * multiplier }
+        when AsciiChem::Model::Molecule
+          enumerate_many(node.nodes, multiplier)
+        when AsciiChem::Model::Group
+          mult = (node.multiplicity || "1").to_i
+          mult = 1 if mult.zero?
+          enumerate_many(node.nodes, multiplier * mult)
+        else
+          nil
+        end
+      end
+
+      def enumerate_many(nodes, multiplier)
+        result = Hash.new(0)
+        nodes.each do |node|
+          sub = enumerate(node, multiplier)
+          return nil if sub.nil?
+
+          sub.each { |element, n| result[element] += n }
+        end
+        result
+      end
+
+      def compute_diffs(reactants, products)
+        all_elements = (reactants.keys + products.keys).uniq.sort
+        all_elements.map do |element|
+          r = reactants.fetch(element, 0)
+          p = products.fetch(element, 0)
+          next if r == p
+
+          "#{element}: #{r} vs #{p}"
+        end.compact.join(", ")
+      end
+    end
+  end
+end

data/lib/asciichem/linter/base.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Linter
+    # Base class for linter checks. Subclasses implement `run(formula)`
+    # and return an array of Diagnostic objects.
+    #
+    # Self-registration: subclasses call `register(:name)` inside their
+    # class body. The Linter module triggers every autoload at load
+    # time so each check file has a chance to register before any API
+    # is queried.
+    class Base
+      class << self
+        def register(name)
+          AsciiChem::Linter::Registry.add(name, self)
+        end
+      end
+
+      def run(_formula)
+        raise NotImplementedError, "#{self.class} must implement #run"
+      end
+
+      protected
+
+      def error(message, node: nil)
+        Diagnostic.new(severity: :error, message: message, node: node)
+      end
+
+      def warning(message, node: nil)
+        Diagnostic.new(severity: :warning, message: message, node: node)
+      end
+
+      def info(message, node: nil)
+        Diagnostic.new(severity: :info, message: message, node: node)
+      end
+
+      # Depth-first walk over every node in the formula. Yields each
+      # node to the block. Uses `Node#children` — adding a new
+      # container class means defining `children` on it; no edits here.
+      def walk(formula)
+        return enum_for(:walk, formula) unless block_given?
+
+        walk_node(formula) { |c| yield c }
+      end
+
+      def walk_node(node)
+        yield node
+        node.children.each { |c| walk_node(c) { |x| yield x } }
+      end
+    end
+  end
+end

data/lib/asciichem/linter/bracket_balance_check.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Linter
+    # Verifies that group brackets are matched. The grammar already
+    # enforces this at parse time, but the linter adds defence in depth
+    # in case future grammar changes or direct model construction
+    # produce malformed trees.
+    class BracketBalanceCheck < Base
+      register :bracket_balance
+
+      def run(formula)
+        diagnostics = []
+        walk(formula) do |node|
+          next unless node.is_a?(AsciiChem::Model::Group)
+
+          case node.bracket
+          when :paren  then check_pair(node, "(", ")", diagnostics)
+          when :square then check_pair(node, "[", "]", diagnostics)
+          when :brace  then check_pair(node, "{", "}", diagnostics)
+          end
+        end
+        diagnostics
+      end
+
+      private
+
+      def check_pair(group, open_char, close_char, diagnostics)
+        if group.open_char != open_char
+          diagnostics << error(
+            "Group bracket kind #{group.bracket.inspect} expected opening #{open_char.inspect}, got #{group.open_char.inspect}",
+            node: group
+          )
+        end
+        return if group.close_char == close_char
+
+        diagnostics << error(
+          "Group bracket kind #{group.bracket.inspect} expected closing #{close_char.inspect}, got #{group.close_char.inspect}",
+          node: group
+        )
+      end
+    end
+  end
+end

data/lib/asciichem/linter/diagnostic.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Linter
+    Diagnostic = Struct.new(:severity, :message, :node, keyword_init: true) do
+      def to_s
+        context = node&.diagnostic_label
+        if context
+          "[#{severity}] #{context}: #{message}"
+        else
+          "[#{severity}] #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/linter/element_validation_check.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Linter
+    # Validates that each Atom's element symbol is in the periodic
+    # table. Catches typos like `Hx`, `Cy`, `Oq` that would otherwise
+    # silently parse and produce nonsense output. Uses
+    # `AsciiChem::PeriodicTable` as the single source of truth.
+    #
+    # Severity is `warning`, not `error` — the parser is total and
+    # might intentionally accept placeholder elements (e.g. `X` for
+    # "unknown halogen" in teaching contexts). The linter flags them
+    # for the user to confirm.
+    class ElementValidationCheck < Base
+      register :element_validation
+
+      def run(formula)
+        diagnostics = []
+        walk(formula) do |node|
+          next unless node.is_a?(AsciiChem::Model::Atom)
+
+          check_atom(node, diagnostics)
+        end
+        diagnostics
+      end
+
+      private
+
+      def check_atom(atom, diagnostics)
+        return if AsciiChem::PeriodicTable.known?(atom.element)
+
+        diagnostics << warning(
+          "Unknown element symbol #{atom.element.inspect}; not in the periodic table",
+          node: atom
+        )
+      end
+    end
+  end
+end

data/lib/asciichem/linter/isotope_sanity_check.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Linter
+    # Sanity-checks isotope mass numbers against the element's atomic
+    # number. The isotope's mass must be ≥ the atomic number (a nucleus
+    # can't have fewer protons than its mass number suggests).
+    #
+    # Atomic-number table is limited to common elements; unknown
+    # elements produce an info diagnostic, not an error.
+    class IsotopeSanityCheck < Base
+      register :isotope_sanity
+
+      def run(formula)
+        diagnostics = []
+        walk(formula) do |node|
+          next unless node.is_a?(AsciiChem::Model::Atom)
+          next unless node.isotope
+
+          check_atom(node, diagnostics)
+        end
+        diagnostics
+      end
+
+      private
+
+      def check_atom(atom, diagnostics)
+        z = AsciiChem::PeriodicTable.atomic_number(atom.element)
+        if z.nil?
+          diagnostics << info(
+            "Element #{atom.element.inspect} not in periodic table; skipping isotope check",
+            node: atom
+          )
+          return
+        end
+
+        mass = atom.isotope.to_i
+        return if mass >= z
+
+        diagnostics << error(
+          "Isotope mass #{mass} is less than atomic number #{z} for #{atom.element}",
+          node: atom
+        )
+      end
+    end
+  end
+end