chemicalml 0.2.0 → 0.3.0

data/lib/chemicalml/convention/violation.rb

@@ -5,18 +5,23 @@ module Chemicalml
     # Value object describing one constraint violation. Severity is
     # either `:error` (document is invalid under the convention) or
     # `:warning` (document is valid but problematic).
+    #
+    # `value` carries the offending value where natural (e.g. the
+    # duplicated atom id, the malformed unit symbol). Optional —
+    # constraints that flag a missing attribute leave `value` nil.
     class Violation
       SEVERITIES = %i[error warning].freeze
 
-      attr_reader :path, :message, :severity, :constraint
+      attr_reader :path, :message, :severity, :constraint, :value
 
-      def initialize(path:, message:, severity: :error, constraint: nil)
+      def initialize(path:, message:, severity: :error, constraint: nil, value: nil)
         raise ArgumentError, "unknown severity: #{severity.inspect}" unless SEVERITIES.include?(severity.to_sym)
 
         @path       = path
         @message    = message
         @severity   = severity.to_sym
         @constraint = constraint
+        @value      = value
         freeze
       end
 
@@ -29,7 +34,8 @@ module Chemicalml
       end
 
       def to_s
-        "#{severity.upcase} #{path}: #{message}"
+        suffix = value.nil? ? '' : " (value=#{value.inspect})"
+        "#{severity.upcase} #{path}: #{message}#{suffix}"
       end
     end
   end

data/lib/chemicalml/convention.rb

@@ -8,32 +8,70 @@ module Chemicalml
   # convention owns its constraint classes; the framework walks
   # whatever was registered.
   #
-  # The five built-in conventions:
+  # The built-in conventions:
   #
   #   molecular            http://www.xml-cml.org/convention/molecular
   #   compchem             http://www.xml-cml.org/convention/compchem
   #   dictionary           http://www.xml-cml.org/convention/dictionary
   #   unit-dictionary      http://www.xml-cml.org/convention/unit-dictionary
   #   unitType-dictionary  http://www.xml-cml.org/convention/unitType-dictionary
+  #   spectroscopy         http://www.xml-cml.org/convention/spectroscopy
+  #   cascade              http://www.xml-cml.org/convention/cascade
+  #   simpleUnit           http://www.xml-cml.org/convention/simpleUnit
   module Convention
-    autoload :Base,                "chemicalml/convention/base"
-    autoload :Compchem,            "chemicalml/convention/compchem"
-    autoload :Constraint,          "chemicalml/convention/constraint"
-    autoload :Dictionary,          "chemicalml/convention/dictionary"
-    autoload :Molecular,           "chemicalml/convention/molecular"
-    autoload :Registry,            "chemicalml/convention/registry"
-    autoload :UnitDictionary,      "chemicalml/convention/unit_dictionary"
-    autoload :UnitTypeDictionary,  "chemicalml/convention/unit_type_dictionary"
-    autoload :Violation,           "chemicalml/convention/violation"
+    autoload :Base,                'chemicalml/convention/base'
+    autoload :Cascade,             'chemicalml/convention/cascade'
+    autoload :Compchem,            'chemicalml/convention/compchem'
+    autoload :Constraint,          'chemicalml/convention/constraint'
+    autoload :Coordinator,         'chemicalml/convention/coordinator'
+    autoload :Detection,           'chemicalml/convention/detection'
+    autoload :Dictionary,          'chemicalml/convention/dictionary'
+    autoload :Molecular,           'chemicalml/convention/molecular'
+    autoload :Registry,            'chemicalml/convention/registry'
+    autoload :SimpleUnit,          'chemicalml/convention/simple_unit'
+    autoload :Spectroscopy,        'chemicalml/convention/spectroscopy'
+    autoload :UnitDictionary,      'chemicalml/convention/unit_dictionary'
+    autoload :UnitTypeDictionary,  'chemicalml/convention/unit_type_dictionary'
+    autoload :ValidationReport,    'chemicalml/convention/validation_report'
+    autoload :Violation,           'chemicalml/convention/violation'
 
-    CONVENTION_NAMESPACE = "http://www.xml-cml.org/convention/".freeze
+    CONVENTION_NAMESPACE = 'http://www.xml-cml.org/convention/'
 
+    # Look up a convention by QName (e.g. "convention:molecular").
+    # @param qname [String] the convention QName.
+    # @return [Module, nil] the convention module, or nil if unknown.
     def self.lookup(qname)
       Registry.lookup(qname)
     end
 
+    # Validate a document against a named convention. Returns the
+    # raw violation list.
+    #
+    # @param document [Lutaml::Model::Serializable] the CML document.
+    # @param qname [String] the convention QName (e.g. "convention:molecular").
+    # @return [Array<Chemicalml::Convention::Violation>] the violations.
+    # @raise [ArgumentError] if the qname is not registered.
     def self.validate(document, qname:)
       Registry.validate(document, qname: qname)
     end
+
+    # Validate and return a structured report (errors + warnings).
+    #
+    # @param document [Lutaml::Model::Serializable] the CML document.
+    # @param qname [String] the convention QName.
+    # @return [Chemicalml::Convention::ValidationReport] the report.
+    def self.validate_report(document, qname:)
+      Registry.validate_report(document, qname: qname)
+    end
+
+    # Auto-detect the convention from the document root's `convention`
+    # attribute and validate.
+    #
+    # @param document [Lutaml::Model::Serializable] the CML document.
+    # @return [Chemicalml::Convention::ValidationReport] the report.
+    # @raise [ArgumentError] if no convention is declared.
+    def self.detect_and_validate(document)
+      Registry.detect_and_validate(document)
+    end
   end
 end

data/lib/chemicalml/dictionary/entry.rb

@@ -6,7 +6,7 @@ module Chemicalml
     # The YAML shape mirrors the structure documented in
     # `TODO.cml-full/05-dictionary-layer.md`.
     class Entry
-      ID_PATTERN = /\A[A-Za-z][A-Za-z0-9._-]*\z/.freeze
+      ID_PATTERN = /\A[A-Za-z][A-Za-z0-9._-]*\z/
 
       attr_reader :id, :term, :definition, :description,
                   :data_type, :unit_type, :units,
@@ -30,7 +30,7 @@ module Chemicalml
         freeze
       end
 
-      def to_h
+      def value_attributes
         h = {
           id: id,
           term: term,
@@ -40,19 +40,19 @@ module Chemicalml
         h[:data_type]   = data_type   if data_type
         h[:unit_type]   = unit_type   if unit_type
         h[:units]       = units       if units
-        h[:enum]        = enum.to_h   if enum
-        h[:links]       = links.map(&:to_h) unless links.empty?
+        h[:enum]        = enum.value_attributes if enum
+        h[:links]       = links.map(&:value_attributes) unless links.empty?
         h[:source_code] = source_code if source_code
         h
       end
 
       def eql?(other)
-        other.is_a?(Entry) && id == other.id && to_h == other.to_h
+        other.is_a?(Entry) && id == other.id && value_attributes == other.value_attributes
       end
       alias == eql?
 
       def hash
-        [id, to_h].hash
+        [id, value_attributes].hash
       end
     end
   end

data/lib/chemicalml/dictionary/enum.rb

@@ -34,7 +34,7 @@ module Chemicalml
         values.include?(value)
       end
 
-      def to_h
+      def value_attributes
         { kind: kind, values: values }
       end
 

data/lib/chemicalml/dictionary/link.rb

@@ -15,17 +15,17 @@ module Chemicalml
         freeze
       end
 
-      def to_h
+      def value_attributes
         { rel: rel, href: href, title: title }.compact
       end
 
       def eql?(other)
-        other.is_a?(Link) && to_h == other.to_h
+        other.is_a?(Link) && value_attributes == other.value_attributes
       end
       alias == eql?
 
       def hash
-        to_h.hash
+        value_attributes.hash
       end
     end
   end

data/lib/chemicalml/dictionary/loader.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "yaml"
+require 'yaml'
 
 module Chemicalml
   module Dictionary
@@ -17,26 +17,26 @@ module Chemicalml
 
       def self.from_hash(hash)
         Model.new(
-          namespace: hash.fetch("namespace"),
-          prefix: hash.fetch("prefix"),
-          title: hash.fetch("title"),
-          description: hash["description"],
-          entries: (hash["entries"] || []).map { |e| build_entry(e) }
+          namespace: hash.fetch('namespace'),
+          prefix: hash.fetch('prefix'),
+          title: hash.fetch('title'),
+          description: hash['description'],
+          entries: (hash['entries'] || []).map { |e| build_entry(e) }
         )
       end
 
       def self.build_entry(h)
         Entry.new(
-          id: h.fetch("id"),
-          term: h.fetch("term"),
-          definition: h.fetch("definition"),
-          description: h["description"],
-          data_type: h["data_type"],
-          unit_type: h["unit_type"],
-          units: h["units"],
-          enum: build_enum(h["enum"]),
-          links: (h["links"] || []).map { |l| build_link(l) },
-          source_code: h["source_code"]
+          id: h.fetch('id'),
+          term: h.fetch('term'),
+          definition: h.fetch('definition'),
+          description: h['description'],
+          data_type: h['data_type'],
+          unit_type: h['unit_type'],
+          units: h['units'],
+          enum: build_enum(h['enum']),
+          links: (h['links'] || []).map { |l| build_link(l) },
+          source_code: h['source_code']
         )
       end
       private_class_method :build_entry
@@ -45,14 +45,14 @@ module Chemicalml
         return nil unless h
 
         Enum.new(
-          kind: h["kind"] || :open,
-          values: h["values"] || []
+          kind: h['kind'] || :open,
+          values: h['values'] || []
         )
       end
       private_class_method :build_enum
 
       def self.build_link(h)
-        Link.new(rel: h.fetch("rel"), href: h.fetch("href"), title: h["title"])
+        Link.new(rel: h.fetch('rel'), href: h.fetch('href'), title: h['title'])
       end
       private_class_method :build_link
     end

data/lib/chemicalml/dictionary/model.rb

@@ -35,29 +35,29 @@ module Chemicalml
         entries.map(&:id)
       end
 
-      def to_h
+      def value_attributes
         {
           namespace: namespace,
           prefix: prefix,
           title: title,
           description: description,
-          entries: entries.map(&:to_h)
+          entries: entries.map(&:value_attributes)
         }
       end
 
       def eql?(other)
-        other.is_a?(Model) && namespace == other.namespace && to_h == other.to_h
+        other.is_a?(Model) && namespace == other.namespace && value_attributes == other.value_attributes
       end
       alias == eql?
 
       def hash
-        [namespace, to_h].hash
+        [namespace, value_attributes].hash
       end
 
       private
 
       def split_qname(qname)
-        qname.to_s.split(":", 2)
+        qname.to_s.split(':', 2)
       end
     end
   end

data/lib/chemicalml/dictionary/registry.rb

@@ -13,7 +13,7 @@ module Chemicalml
       @mutex = Mutex.new
 
       def self.lookup(qname)
-        prefix, id = qname.to_s.split(":", 2)
+        prefix, id = qname.to_s.split(':', 2)
         return nil unless id
 
         dict = load_by_prefix(prefix)
@@ -39,7 +39,7 @@ module Chemicalml
 
       def self.load_by_prefix(prefix)
         manifest.each do |name, info|
-          return load_builtin(name) if info["prefix"] == prefix
+          return load_builtin(name) if info['prefix'] == prefix
         end
         nil
       end
@@ -49,27 +49,27 @@ module Chemicalml
       end
 
       def self.builtin_names
-        Dir.glob(File.join(BUILTIN_DIR, "*.yaml"))
-           .reject { |p| File.basename(p).start_with?("_") }
-           .map { |p| File.basename(p, ".yaml").to_sym }
+        Dir.glob(File.join(BUILTIN_DIR, '*.yaml'))
+           .reject { |p| File.basename(p).start_with?('_') }
+           .map { |p| File.basename(p, '.yaml').to_sym }
            .sort
       end
 
       def self.manifest
         @manifest ||= begin
-          path = File.join(BUILTIN_DIR, "_index.yaml")
+          path = File.join(BUILTIN_DIR, '_index.yaml')
           if File.exist?(path)
             YAML.load_file(path) || {}
           else
-            builtin_names.each_with_object({}) do |name, h|
-              h[name.to_s] = { "prefix" => name.to_s }
+            builtin_names.to_h do |name|
+              [name.to_s, { 'prefix' => name.to_s }]
             end
           end
         end
       end
       private_class_method :manifest
 
-      require "yaml"
+      require 'yaml'
     end
   end
 end

data/lib/chemicalml/dictionary.rb

@@ -8,17 +8,21 @@ module Chemicalml
   # Built-in dictionaries ship as YAML under `data/dictionaries/` and
   # are loaded into `Chemicalml::Dictionary::Registry` lazily.
   module Dictionary
-    autoload :Entry,   "chemicalml/dictionary/entry"
-    autoload :Enum,    "chemicalml/dictionary/enum"
-    autoload :Link,    "chemicalml/dictionary/link"
-    autoload :Loader,  "chemicalml/dictionary/loader"
-    autoload :Model,   "chemicalml/dictionary/model"
-    autoload :Registry, "chemicalml/dictionary/registry"
+    autoload :Entry,   'chemicalml/dictionary/entry'
+    autoload :Enum,    'chemicalml/dictionary/enum'
+    autoload :Link,    'chemicalml/dictionary/link'
+    autoload :Loader,  'chemicalml/dictionary/loader'
+    autoload :Model,   'chemicalml/dictionary/model'
+    autoload :Registry, 'chemicalml/dictionary/registry'
 
-    BUILTIN_DIR = File.expand_path("../../data/dictionaries", __dir__).freeze
+    BUILTIN_DIR = File.expand_path('../../data/dictionaries', __dir__).freeze
 
-    # Convenience: load a built-in dictionary by short name
-    # (e.g. `:compchem`). Returns a `Chemicalml::Dictionary::Model`.
+    # Convenience: load a built-in dictionary by short name.
+    #
+    # @param name [Symbol, String] the dictionary short name (YAML
+    #   filename stem, e.g. `:compchem`, `:cml`).
+    # @return [Chemicalml::Dictionary::Model] the loaded dictionary.
+    # @raise [KeyError] if `name` is not a built-in dictionary.
     def self.load(name)
       Registry.load_builtin(name)
     end

data/lib/chemicalml/logger.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Chemicalml
+  # Logger used across the CLI and API. Wraps Ruby's ::Logger and can
+  # bridge to Thor's `say` / `say_error` when running under a Thor
+  # dispatcher — that gives coloured output on the terminal while
+  # plain `Logger.new($stderr)` works for library callers.
+  #
+  # Severity routing under Thor:
+  #   debug → suppressed (set level manually if needed)
+  #   info  → say (green-ish, $stdout)
+  #   warn  → say_error with :yellow ($stderr)
+  #   error → say_error with :red   ($stderr)
+  #   fatal → say_error with :red   ($stderr)
+  class Logger < ::Logger
+    attr_reader :thor_shell
+
+    # Bridge to a Thor shell instance (self inside a Thor command).
+    # When set, info/warn/error route through Thor for coloured output.
+    def thor_shell=(shell)
+      @thor_shell = shell
+    end
+
+    def add(severity, message = nil, progname = nil)
+      return super unless thor_shell
+      return true if severity < level
+
+      msg = message || progname
+      case severity
+      when ERROR, FATAL
+        thor_shell.say_error(msg.to_s, :red)
+      when WARN
+        thor_shell.say_error(msg.to_s, :yellow)
+      else
+        thor_shell.say(msg.to_s)
+      end
+    end
+
+    # Convenience: create a default logger that writes to $stderr at
+    # INFO level. Used when no logger is explicitly provided.
+    def self.default
+      new($stderr).tap { |l| l.level = INFO }
+    end
+  end
+end

data/lib/chemicalml/schema/definition.rb

@@ -19,7 +19,7 @@ module Chemicalml
       end
 
       def wire_namespace_constant
-        ruby_namespace.split("::").reduce(Object) { |ns, name| ns.const_get(name) }
+        ruby_namespace.split('::').reduce(Object) { |ns, name| ns.const_get(name) }
       end
 
       def eql?(other)
@@ -34,7 +34,7 @@ module Chemicalml
       private
 
       def project_root
-        File.expand_path("../../..", __dir__)
+        File.expand_path('../../..', __dir__)
       end
     end
   end

data/lib/chemicalml/schema.rb

@@ -9,10 +9,10 @@ module Chemicalml
   # `reference-docs/schemas/`. They are never modified or regenerated
   # from code.
   module Schema
-    autoload :Definition, "chemicalml/schema/definition"
-    autoload :Registry,   "chemicalml/schema/registry"
+    autoload :Definition, 'chemicalml/schema/definition'
+    autoload :Registry,   'chemicalml/schema/registry'
 
-    CML_XML_NAMESPACE = "http://www.xml-cml.org/schema"
+    CML_XML_NAMESPACE = 'http://www.xml-cml.org/schema'
 
     # Built-in versions registered at load time. Adding a new CML schema
     # version = appending an entry here and creating the matching
@@ -20,15 +20,15 @@ module Chemicalml
     BUILTIN = {
       schema24: Definition.new(
         version: :schema24,
-        xsd_path: "reference-docs/schemas/schema24/schema.xsd",
+        xsd_path: 'reference-docs/schemas/schema24/schema.xsd',
         xml_namespace: CML_XML_NAMESPACE,
-        ruby_namespace: "Chemicalml::Cml::Schema24"
+        ruby_namespace: 'Chemicalml::Cml::Schema24'
       ),
       schema3: Definition.new(
         version: :schema3,
-        xsd_path: "reference-docs/schemas/schema3/schema.xsd",
+        xsd_path: 'reference-docs/schemas/schema3/schema.xsd',
         xml_namespace: CML_XML_NAMESPACE,
-        ruby_namespace: "Chemicalml::Cml::Schema3"
+        ruby_namespace: 'Chemicalml::Cml::Schema3'
       )
     }.freeze
   end

data/lib/chemicalml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chemicalml
-  VERSION = "0.2.0"
+  VERSION = '0.3.0'
 end

data/lib/chemicalml/versioned_parser.rb

@@ -9,19 +9,37 @@ module Chemicalml
   # (Document), `<module>` (compchem Module), `<dictionary>`,
   # `<unitList>`, `<unitTypeList>`, and the legacy standalone roots
   # `<molecule>`, `<reaction>`, `<reactionList>`.
+  #
+  # ---
+  #
+  # XML processing boundary (read me):
+  #
+  # The gem uses `lutaml-model` for ALL XML parsing and serialization
+  # — 242 wire classes extend `Lutaml::Model::Serializable`, and no
+  # `lib/` file defines `to_xml`/`from_xml`/`to_h`/`from_h` on a
+  # model class. Zero Nokogiri/REXML references in `lib/`.
+  #
+  # This file has TWO pre-processing helpers — `root_element_of` and
+  # `inject_namespace` — that operate on the XML *string* before
+  # `Lutaml::Model::Serializable.from_xml` is called. They are NOT
+  # serialization: they don't construct XML nodes, don't traverse
+  # trees, don't map attributes to model fields. They are input
+  # normalization so callers can pass namespace-less XML or rely on
+  # the parser to dispatch by root element name. The actual parse
+  # happens on the `const_get(class_name).from_xml(...)` call below.
   module VersionedParser
     # Maps root element name → constant name on the schema module.
     # Adding a new root type = adding one entry here. OCP — no
     # existing code changes.
     KNOWN_ROOTS = {
-      "cml"          => :Document,
-      "molecule"     => :Molecule,
-      "reaction"     => :Reaction,
-      "reactionList" => :ReactionList,
-      "module"       => :Module,
-      "dictionary"   => :Dictionary,
-      "unitList"     => :UnitList,
-      "unitTypeList" => :UnitTypeList,
+      'cml' => :Document,
+      'molecule' => :Molecule,
+      'reaction' => :Reaction,
+      'reactionList' => :ReactionList,
+      'module' => :Module,
+      'dictionary' => :Dictionary,
+      'unitList' => :UnitList,
+      'unitTypeList' => :UnitTypeList
     }.freeze
 
     def parse(xml, namespace_exist: true)
@@ -39,7 +57,7 @@ module Chemicalml
       unless const_defined?(class_name, false)
         raise ArgumentError,
               "#{name} does not define #{class_name} " \
-              "(not all root elements exist in every schema version)"
+              '(not all root elements exist in every schema version)'
       end
 
       const_get(class_name).from_xml(
@@ -65,7 +83,7 @@ module Chemicalml
       match = xml.match(/<([a-zA-Z][\w.-]*)(?::[a-zA-Z][\w.-]*)?/)
       return match[1] if match
 
-      raise ArgumentError, "could not detect root element in XML"
+      raise ArgumentError, 'could not detect root element in XML'
     end
 
     def xml_input(xml, namespace_exist, root)