chemicalml 0.2.0 → 0.2.1

data/lib/chemicalml/convention/coordinator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # Single-pass constraint dispatcher. Replaces the previous
+    # O(N*C) walk (every constraint walked the whole tree) with
+    # O(N + total_applicable) — one tree walk per validation, with
+    # each node dispatched only to constraints that declared
+    # `applies_to` matching one of the node's ancestors.
+    #
+    # Constraints that don't declare `applies_to` fall into a
+    # default "all nodes" bucket and run for every visited node,
+    # preserving backward compatibility.
+    class Coordinator
+      attr_reader :document_constraints, :node_constraints
+
+      def initialize(constraint_classes)
+        @document_constraints = constraint_classes
+                                  .select { |c| c < Constraint::DocumentConstraint }
+                                  .map(&:new)
+        @node_constraints = constraint_constraints(constraint_classes)
+                              .map(&:new)
+        @always_applicable = []
+        @by_role = Hash.new { |h, k| h[k] = [] }
+        @node_constraints.each { |c| register(c) }
+      end
+
+      def validate(document)
+        violations = @document_constraints.flat_map do |constraint|
+          Array(constraint.check(document))
+        end
+        return violations unless visitable?(document)
+
+        walk(document) do |node, path|
+          applicable_for(node).each do |constraint|
+            violations.concat(Array(constraint.check_node(node, path)))
+          end
+        end
+        violations
+      end
+
+      private
+
+      def constraint_constraints(classes)
+        classes.select { |c| c < Constraint::NodeConstraint }
+      end
+
+      def register(constraint)
+        roles = constraint.class.applies_to_roles
+        if roles.nil? || roles.empty?
+          @always_applicable << constraint
+        else
+          roles.each { |role| @by_role[role] << constraint }
+        end
+      end
+
+      def visitable?(node)
+        node.is_a?(Chemicalml::Cml::Visitable)
+      end
+
+      def applicable_for(node)
+        applicable = @always_applicable
+        node.class.ancestors.each do |ancestor|
+          next unless ancestor.is_a?(::Module)
+          bucket = @by_role[ancestor]
+          next unless bucket
+
+          applicable += bucket
+        end
+        applicable
+      end
+
+      def walk(node, path = [], &block)
+        return unless node
+        return unless visitable?(node)
+
+        yield(node, path)
+        node.wire_children.each do |child|
+          walk(child, path + [describe(child)], &block)
+        end
+      end
+
+      def describe(node)
+        id_value = node.node_id
+        id_value ? "#{node.element_name}[#{id_value}]" : node.element_name
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/detection.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # Convention detection from a wire document. Reads the
+    # `convention` attribute from the root element (Document, Module,
+    # Molecule, Dictionary, UnitList, or UnitTypeList) and returns
+    # the QName string (e.g. "convention:molecular").
+    #
+    # Used by `Registry.detect_and_validate` and reusable by callers
+    # that want to know which convention a document declares without
+    # running validation.
+    module Detection
+      CONVENTION_ROOTS = [
+        Chemicalml::Cml::Role::Document,
+        Chemicalml::Cml::Role::Module,
+        Chemicalml::Cml::Role::Molecule,
+        Chemicalml::Cml::Role::Dictionary,
+        Chemicalml::Cml::Role::UnitList,
+        Chemicalml::Cml::Role::UnitTypeList
+      ].freeze
+
+      def self.convention_of(document)
+        CONVENTION_ROOTS.each do |role|
+          next unless document.is_a?(role)
+
+          return document.convention if document.convention
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary/constraints/dictionary_must_have_namespace.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Dictionary
+      module Constraints
+        # A `<dictionary>` element MUST have a `namespace` attribute
+        # whose value is a valid URI defining the scope within which
+        # the entry terms are unique.
+        class DictionaryMustHaveNamespace < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::Dictionary
+          def check_node(node, path)
+            return [] unless node.namespace.to_s.empty?
+
+            [violation(path: path.join('/'),
+                       message: 'dictionary must have a namespace attribute')]
+          end
+
+          private
+
+          def dictionary?(node)
+            node.is_a?(Chemicalml::Cml::Role::Dictionary)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary/constraints/dictionary_namespace_should_end_with_slash_or_hash.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Dictionary
+      module Constraints
+        # The `namespace` URI SHOULD end with `/` or `#` so terms can
+        # be referenced by appending them to the URI. Warning level.
+        class DictionaryNamespaceShouldEndWithSlashOrHash < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::Dictionary
+          def check_node(node, path)
+
+            ns = node.namespace.to_s
+            return [] if ns.empty?
+            return [] if ns.end_with?('/', '#')
+
+            [violation(path: path.join('/'),
+                       message: "dictionary namespace #{ns.inspect} should end with / or # " \
+                                'so terms can be referenced by appending',
+                       severity: :warning)]
+          end
+
+          private
+
+          def dictionary?(node)
+            node.is_a?(Chemicalml::Cml::Role::Dictionary)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary/constraints/entry_id_must_match_pattern.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Dictionary
+      module Constraints
+        # An `<entry>` `id` MUST match `[A-Za-z][A-Za-z0-9._-]*` —
+        # start with a letter, followed by letters/digits/dot/hyphen/
+        # underscore. Mirrors the upstream IdStartChar / IdChar BNF.
+        class EntryIdMustMatchPattern < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::DictionaryEntry
+          PATTERN = /\A[A-Za-z][A-Za-z0-9._-]*\z/
+
+          def check_node(node, path)
+
+            id = node.id.to_s
+            return [] if id.empty?
+            return [] if id.match?(PATTERN)
+
+            [violation(path: path.join('/'),
+                       message: "entry id #{id.inspect} must match [A-Za-z][A-Za-z0-9._-]*")]
+          end
+
+          private
+
+          def entry?(node)
+            node.is_a?(Chemicalml::Cml::Role::DictionaryEntry)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary/constraints/entry_ids_unique_within_dictionary.rb

@@ -7,16 +7,16 @@ module Chemicalml
         # Entry ids MUST be unique within the parent dictionary per
         # the dictionary convention.
         class EntryIdsUniqueWithinDictionary < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::Dictionary
           def check_node(node, path)
-            return [] unless dictionary?(node)
 
             entries = node.entries || []
-            ids = entries.map { |e| e.id }.compact
+            ids = entries.map(&:id).compact
             duplicates = ids.group_by { |x| x }.select { |_, v| v.length > 1 }.keys
             return [] if duplicates.empty?
 
             duplicates.map do |dup|
-              violation(path: path.join("/"),
+              violation(path: path.join('/'),
                         message: "duplicate entry id #{dup.inspect} within dictionary")
             end
           end

data/lib/chemicalml/convention/dictionary/constraints/entry_must_contain_definition.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Dictionary
+      module Constraints
+        # An `<entry>` MUST contain a single `definition` child
+        # element. The schema allows it as a string; this constraint
+        # enforces presence.
+        class EntryMustContainDefinition < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::DictionaryEntry
+          def check_node(node, path)
+            return [] unless node.definition.to_s.strip.empty?
+
+            [violation(path: path.join('/'),
+                       message: "entry #{node.id.inspect} must contain a single definition child")]
+          end
+
+          private
+
+          def entry?(node)
+            node.is_a?(Chemicalml::Cml::Role::DictionaryEntry)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary/constraints/entry_must_have_id_and_term.rb

@@ -7,17 +7,17 @@ module Chemicalml
         # Every entry MUST have an `id` and a `term` attribute per the
         # dictionary convention.
         class EntryMustHaveIdAndTerm < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::DictionaryEntry
           def check_node(node, path)
-            return [] unless entry?(node)
 
             violations = []
             if node.id.to_s.empty?
-              violations << violation(path: path.join("/"),
-                                      message: "entry must have an id attribute")
+              violations << violation(path: path.join('/'),
+                                      message: 'entry must have an id attribute')
             end
             if node.term.to_s.empty?
-              violations << violation(path: path.join("/"),
-                                      message: "entry must have a term attribute")
+              violations << violation(path: path.join('/'),
+                                      message: 'entry must have a term attribute')
             end
             violations
           end

data/lib/chemicalml/convention/dictionary/constraints/entry_must_have_unit_type.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Dictionary
+      module Constraints
+        # An `<entry>` MUST have a `unitType` attribute. Entries
+        # describing concepts that should not have units (e.g. name
+        # of a program) should reference `none` in the standard CML
+        # unitType dictionary.
+        class EntryMustHaveUnitType < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::DictionaryEntry
+          def check_node(node, path)
+            return [] unless node.unit_type.to_s.empty?
+
+            [violation(path: path.join('/'),
+                       message: "entry #{node.id.inspect} must have a unitType attribute " \
+                                "(use 'none' for concepts without units)")]
+          end
+
+          private
+
+          def entry?(node)
+            node.is_a?(Chemicalml::Cml::Role::DictionaryEntry)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary/constraints/entry_units_co_constraints.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Dictionary
+      module Constraints
+        # Co-constraint between `unitType` and `units`:
+        #
+        # - If `unitType` is `unknown`, `units` MUST NOT be present.
+        # - If `unitType` is `none`, `units` MUST be present and point
+        #   to `http://www.xml-cml.org/unit/si#none`.
+        class EntryUnitsCoConstraints < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::DictionaryEntry
+          NONE_UNITS = 'http://www.xml-cml.org/unit/si#none'
+
+          def check_node(node, path)
+
+            unit_type = node.unit_type.to_s
+            units = node.units.to_s
+            violations = []
+
+            if unit_type == 'unknown' && !units.empty?
+              violations << violation(path: path.join('/'),
+                                      message: "entry #{node.id.inspect} has unitType 'unknown' " \
+                                               'and therefore must not have units')
+            end
+            if unit_type == 'none' && units != NONE_UNITS
+              violations << violation(path: path.join('/'),
+                                      message: "entry #{node.id.inspect} has unitType 'none' — " \
+                                               "units must be #{NONE_UNITS.inspect}")
+            end
+            violations
+          end
+
+          private
+
+          def entry?(node)
+            node.is_a?(Chemicalml::Cml::Role::DictionaryEntry)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/dictionary/constraints.rb

@@ -8,6 +8,18 @@ module Chemicalml
                  "chemicalml/convention/dictionary/constraints/entry_must_have_id_and_term"
         autoload :EntryIdsUniqueWithinDictionary,
                  "chemicalml/convention/dictionary/constraints/entry_ids_unique_within_dictionary"
+        autoload :DictionaryMustHaveNamespace,
+                 "chemicalml/convention/dictionary/constraints/dictionary_must_have_namespace"
+        autoload :DictionaryNamespaceShouldEndWithSlashOrHash,
+                 "chemicalml/convention/dictionary/constraints/dictionary_namespace_should_end_with_slash_or_hash"
+        autoload :EntryMustContainDefinition,
+                 "chemicalml/convention/dictionary/constraints/entry_must_contain_definition"
+        autoload :EntryIdMustMatchPattern,
+                 "chemicalml/convention/dictionary/constraints/entry_id_must_match_pattern"
+        autoload :EntryMustHaveUnitType,
+                 "chemicalml/convention/dictionary/constraints/entry_must_have_unit_type"
+        autoload :EntryUnitsCoConstraints,
+                 "chemicalml/convention/dictionary/constraints/entry_units_co_constraints"
       end
     end
   end

data/lib/chemicalml/convention/dictionary.rb

@@ -23,6 +23,12 @@ module Chemicalml
 
       register Constraints::EntryMustHaveIdAndTerm
       register Constraints::EntryIdsUniqueWithinDictionary
+      register Constraints::DictionaryMustHaveNamespace
+      register Constraints::DictionaryNamespaceShouldEndWithSlashOrHash
+      register Constraints::EntryMustContainDefinition
+      register Constraints::EntryIdMustMatchPattern
+      register Constraints::EntryMustHaveUnitType
+      register Constraints::EntryUnitsCoConstraints
     end
   end
 end

data/lib/chemicalml/convention/molecular/constraints/atom_array_must_be_child_of_molecule_or_formula.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # Molecular convention: `<atomArray>` MUST be a child of
+        # `<molecule>` or `<formula>`. Any other parent is invalid.
+        # Checked from the parent's perspective during the walk —
+        # when visiting a non-molecule/non-formula node, look for
+        # misplaced atomArray children.
+        class AtomArrayMustBeChildOfMoleculeOrFormula < Chemicalml::Convention::Constraint::NodeConstraint
+          def check_node(node, path)
+            return [] if allowed_parent?(node)
+
+            misplaced = node.wire_children.select { |c| atom_array?(c) }
+            misplaced.map do |child|
+              violation(
+                path: (path + [describe(node), describe(child)]).join('/'),
+                message: 'atomArray must be a child of molecule or formula, ' \
+                         "but appears under #{node.element_name.inspect}"
+              )
+            end
+          end
+
+          private
+
+          def allowed_parent?(node)
+            node.is_a?(Chemicalml::Cml::Role::Molecule) ||
+              node.is_a?(Chemicalml::Cml::Role::Formula)
+          end
+
+          def atom_array?(node)
+            node.is_a?(Chemicalml::Cml::Role::AtomArray)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/atom_array_must_contain_atoms.rb

@@ -7,15 +7,15 @@ module Chemicalml
         # `atomArray` MUST contain at least one `atom` child per the
         # molecular convention.
         class AtomArrayMustContainAtoms < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::Molecule
           def check_node(node, path)
-            return [] unless molecule?(node)
             return [] unless node.atom_array
 
             atoms = node.atom_array.atoms || []
             return [] unless atoms.empty?
 
-            [violation(path: path.empty? ? "molecule" : path.join("/"),
-                       message: "atomArray must contain at least one atom")]
+            [violation(path: path.empty? ? 'molecule' : path.join('/'),
+                       message: 'atomArray must contain at least one atom')]
           end
 
           private

data/lib/chemicalml/convention/molecular/constraints/atom_coordinates_must_be_paired.rb

@@ -5,23 +5,23 @@ module Chemicalml
     module Molecular
       module Constraints
         class AtomCoordinatesMustBePaired < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::Atom
           def check_node(node, path)
-            return [] unless node.is_a?(Chemicalml::Cml::Role::Atom)
 
             violations = []
             has_x2 = !node.x2.to_s.empty?
             has_y2 = !node.y2.to_s.empty?
             if has_x2 != has_y2
-              violations << violation(path: path.empty? ? "atom" : path.join("/"),
-                                      message: "x2 and y2 must both be present or both absent")
+              violations << violation(path: path.empty? ? 'atom' : path.join('/'),
+                                      message: 'x2 and y2 must both be present or both absent')
             end
 
             has_x3 = !node.x3.to_s.empty?
             has_y3 = !node.y3.to_s.empty?
             has_z3 = !node.z3.to_s.empty?
             if [has_x3, has_y3, has_z3].any? && ![has_x3, has_y3, has_z3].all?
-              violations << violation(path: path.empty? ? "atom" : path.join("/"),
-                                      message: "x3, y3, and z3 must all be present together")
+              violations << violation(path: path.empty? ? 'atom' : path.join('/'),
+                                      message: 'x3, y3, and z3 must all be present together')
             end
             violations
           end

data/lib/chemicalml/convention/molecular/constraints/atom_id_must_match_pattern.rb

@@ -5,18 +5,18 @@ module Chemicalml
     module Molecular
       module Constraints
         class AtomIdMustMatchPattern < Chemicalml::Convention::Constraint::NodeConstraint
-          ID_PATTERN = /\A[A-Za-z][A-Za-z0-9._\-]*\z/.freeze
+          applies_to Chemicalml::Cml::Role::Atom
+          ID_PATTERN = /\A[A-Za-z][A-Za-z0-9._-]*\z/
 
           def check_node(node, path)
-            return [] unless node.is_a?(Chemicalml::Cml::Role::Atom)
 
             id = node.id.to_s
             return [] if id.empty?
             return [] if id.match?(ID_PATTERN)
 
-            [violation(path: path.empty? ? "atom" : path.join("/"),
+            [violation(path: path.empty? ? 'atom' : path.join('/'),
                        message: "atom id #{id.inspect} must start with a letter and " \
-                                "contain only letters, digits, dot, hyphen, or underscore",
+                                'contain only letters, digits, dot, hyphen, or underscore',
                        severity: :warning)]
           end
         end

data/lib/chemicalml/convention/molecular/constraints/atom_ids_unique_within_molecule.rb

@@ -16,7 +16,7 @@ module Chemicalml
               duplicates = ids.group_by { |x| x }.select { |_, v| v.length > 1 }.keys
               duplicates.each do |dup|
                 violations << violation(
-                  path: path.empty? ? "molecule[#{node.id}]" : path.join("/"),
+                  path: path.empty? ? "molecule[#{node.id}]" : path.join('/'),
                   message: "duplicate atom id #{dup.inspect} within molecule #{node.id.inspect}"
                 )
               end
@@ -33,7 +33,7 @@ module Chemicalml
           def atom_ids_within(molecule)
             return [] unless molecule.atom_array
 
-            (molecule.atom_array.atoms || []).map { |a| a.id }.compact
+            (molecule.atom_array.atoms || []).map(&:id).compact
           end
         end
       end

data/lib/chemicalml/convention/molecular/constraints/atom_must_have_element_type.rb

@@ -5,13 +5,13 @@ module Chemicalml
     module Molecular
       module Constraints
         class AtomMustHaveElementType < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::Atom
           def check_node(node, path)
-            return [] unless node.is_a?(Chemicalml::Cml::Role::Atom)
 
             return [] unless node.element_type.to_s.empty?
 
-            [violation(path: path.empty? ? "atom" : path.join("/"),
-                       message: "atom must have an elementType attribute")]
+            [violation(path: path.empty? ? 'atom' : path.join('/'),
+                       message: 'atom must have an elementType attribute')]
           end
         end
       end

data/lib/chemicalml/convention/molecular/constraints/atom_must_have_id.rb

@@ -5,13 +5,13 @@ module Chemicalml
     module Molecular
       module Constraints
         class AtomMustHaveId < Chemicalml::Convention::Constraint::NodeConstraint
+          applies_to Chemicalml::Cml::Role::Atom
           def check_node(node, path)
-            return [] unless node.is_a?(Chemicalml::Cml::Role::Atom)
 
             return [] unless node.id.to_s.empty?
 
-            [violation(path: path.empty? ? "atom" : path.join("/"),
-                       message: "atom must have an id attribute")]
+            [violation(path: path.empty? ? 'atom' : path.join('/'),
+                       message: 'atom must have an id attribute')]
           end
         end
       end

data/lib/chemicalml/convention/molecular/constraints/bond_array_must_be_child_of_molecule.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # Molecular convention: `<bondArray>` MUST be a child of
+        # `<molecule>`. Any other parent is invalid.
+        class BondArrayMustBeChildOfMolecule < Chemicalml::Convention::Constraint::NodeConstraint
+          def check_node(node, path)
+            return [] if molecule?(node)
+
+            misplaced = node.wire_children.select { |c| bond_array?(c) }
+            misplaced.map do |child|
+              violation(
+                path: (path + [describe(node), describe(child)]).join('/'),
+                message: 'bondArray must be a child of molecule, ' \
+                         "but appears under #{node.element_name.inspect}"
+              )
+            end
+          end
+
+          private
+
+          def molecule?(node)
+            node.is_a?(Chemicalml::Cml::Role::Molecule)
+          end
+
+          def bond_array?(node)
+            node.is_a?(Chemicalml::Cml::Role::BondArray)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/bond_ids_unique_within_molecule.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # Molecular convention: a `<bond>` `id` MUST be unique within
+        # the eldest containing molecule. Mirrors the existing
+        # `AtomIdsUniqueWithinMolecule` constraint for bonds.
+        class BondIdsUniqueWithinMolecule < Chemicalml::Convention::Constraint::DocumentConstraint
+          def check(document)
+            violations = []
+            walk_nodes(document) do |node, path|
+              next unless molecule?(node)
+
+              ids = bond_ids_within(node)
+              duplicates = ids.group_by { |x| x }.select { |_, v| v.length > 1 }.keys
+              duplicates.each do |dup|
+                violations << violation(
+                  path: (path + [describe(node)]).join('/'),
+                  message: "duplicate bond id #{dup.inspect} within molecule #{node.id.inspect}"
+                )
+              end
+            end
+            violations
+          end
+
+          private
+
+          def molecule?(node)
+            node.is_a?(Chemicalml::Cml::Role::Molecule)
+          end
+
+          def bond_ids_within(molecule)
+            return [] unless molecule.bond_array
+
+            (molecule.bond_array.bonds || []).map(&:id).compact
+          end
+        end
+      end
+    end
+  end
+end