chemicalml 0.2.1 → 0.3.0

data/docs/generate_constraint_docs.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "chemicalml"
+
+# Auto-generated documentation of every registered convention
+# constraint. Run via `bundle exec rake docs:constraints` or
+# `bundle exec ruby docs/generate_constraint_docs.rb`.
+#
+# Single source of truth: derived from `Convention::Registry.each_constraint`.
+# Do not edit `docs/constraints.md` by hand — regenerate.
+
+output = []
+output << "# Registered Convention Constraints"
+output << ""
+output << "Auto-generated from `Chemicalml::Convention::Registry.each_constraint`."
+output << "Last regenerated: #{Time.now.utc.iso8601}."
+output << ""
+output << "Total constraints: **#{Chemicalml::Convention::Registry.total_constraint_count}**"
+output << ""
+
+Chemicalml::Convention::Registry.each do |conv|
+  output << "## #{conv.qname}"
+  output << ""
+  output << "- **Namespace**: `#{conv.namespace_uri}`"
+  output << "- **Constraint count**: #{conv.constraint_count}"
+  output << ""
+
+  output << "| Constraint | Applies to | Description |"
+  output << "|---|---|---|"
+  conv.constraints.each do |klass|
+    name = klass.name.split("::").last
+    roles = klass.applies_to_roles
+    applies = roles.nil? ? "_(document-wide)_" : roles.map { |r| r.name.split("::").last }.join(", ")
+    desc = klass.description
+    desc = "" if desc == name
+    desc_escaped = desc.gsub("|", "\\|")
+    output << "| `#{name}` | #{applies} | #{desc_escaped} |"
+  end
+  output << ""
+end
+
+path = File.expand_path("constraints.md", __dir__)
+File.write(path, output.join("\n"))
+puts "Wrote #{path} (#{Chemicalml::Convention::Registry.total_constraint_count} constraints)"

data/exe/chemicalml

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "chemicalml"
+exit Chemicalml::Cli.run(ARGV)

data/lib/chemicalml/cli/base.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Chemicalml
+  module Cli
+    # Thor-based dispatcher. Each command delegates to a dedicated
+    # `Chemicalml::Cli::*Command` class invoked as
+    # `MyCommand.new.run(options)`, where `options` is a single hash
+    # carrying both positional args (keyed by name) and flags.
+    #
+    # A `Chemicalml::Logger` bridged to Thor's shell is injected into
+    # every command — so info/warn/error get coloured output on the
+    # terminal while remaining loggable for library callers.
+    class Base < Thor
+      private
+
+      # Build a logger bridged to this Thor instance for coloured output.
+      def bridged_logger
+        Chemicalml::Logger.default.tap { |l| l.thor_shell = self }
+      end
+
+      public
+
+      desc 'validate FILE', 'Validate a CML file against its declared convention'
+      method_option :json, type: :boolean, aliases: '-j',
+                           desc: 'Emit machine-readable JSON output'
+      def validate(file)
+        ValidateCommand.new(logger: bridged_logger).run(file: file, json: options[:json])
+      end
+
+      desc 'inspect FILE', 'Print a tree-style summary of the document'
+      def inspect(file)
+        InspectCommand.new(logger: bridged_logger).run(file: file)
+      end
+
+      desc 'conventions', 'List registered conventions'
+      def conventions
+        ConventionsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'dictionaries', 'List built-in dictionaries'
+      def dictionaries
+        DictionariesCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'elements', 'List all CML wire classes'
+      def elements
+        ElementsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'constraints', 'List all registered constraints'
+      def constraints
+        ConstraintsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'enums', 'List all XSD enum constants'
+      def enums
+        EnumsCommand.new(logger: bridged_logger).run({})
+      end
+
+      desc 'info ELEMENT', 'Show details about a CML element'
+      def info(element)
+        InfoCommand.new(logger: bridged_logger).run(element: element)
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/command.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # Base class for every command. Subclasses implement `#run(options)`.
+    #
+    # Each command receives a `Chemicalml::Logger` in its constructor.
+    # When dispatched via Thor (the normal CLI path), the logger is
+    # bridged to Thor's shell for coloured output. When invoked
+    # directly (MyCommand.new.run(options)), the logger writes plain
+    # text to $stderr.
+    class Command
+      attr_reader :logger
+
+      # @param logger [Chemicalml::Logger] the logger to use. Defaults
+      #   to a plain stderr logger. The Thor dispatcher passes one
+      #   bridged to Thor's shell for colour.
+      def initialize(logger: Chemicalml::Logger.default)
+        @logger = logger
+      end
+
+      class << self
+        def run(options = {}, logger: Chemicalml::Logger.default)
+          new(logger: logger).run(options)
+        end
+      end
+
+      def run(_options = {})
+        raise NotImplementedError, "#{self.class} must implement #run"
+      end
+
+      private
+
+      def puts(*args)
+        $stdout.puts(*args)
+      end
+
+      def stderr(*args)
+        $stderr.puts(*args)
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/constraints_command.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml constraints` — list every registered constraint
+    # across every convention with its applies_to roles.
+    class ConstraintsCommand < Command
+      def run(_options = {})
+        current = nil
+        Chemicalml::Convention::Registry.each_constraint do |conv, klass|
+          unless conv.qname == current
+            current = conv.qname
+            puts ''
+            puts "=== #{current} (#{conv.constraint_count}) ==="
+          end
+          name = klass.name.split('::').last
+          applies = klass.applies_to_roles
+          roles_str = applies.nil? ? '' : "  → #{applies.map { |r| r.name.split('::').last }.join(', ')}"
+          puts "  #{name}#{roles_str}"
+          desc = klass.description
+          puts "    #{desc}" unless desc == name
+        end
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/conventions_command.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml conventions` — list every registered convention
+    # by QName, sorted.
+    class ConventionsCommand < Command
+      def run(_options = {})
+        Chemicalml::Convention::Registry.builtin_qnames.sort.each { |q| puts q }
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/dictionaries_command.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml dictionaries` — list built-in YAML dictionaries
+    # by short name.
+    class DictionariesCommand < Command
+      def run(_options = {})
+        Chemicalml::Dictionary::Registry.builtin_names.each { |n| puts n }
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/elements_command.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml elements` — list every CML wire class registered
+    # in Schema3 with its XML element name.
+    class ElementsCommand < Command
+      def run(_options = {})
+        Chemicalml::Cml::Schema3::Configuration.ensure_registered!
+        Chemicalml::Cml::Elements::ALL.sort.each do |cls, xml_id|
+          puts "#{cls.to_s.ljust(25)} → <#{xml_id}>"
+        end
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/enums_command.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml enums` — list every `Cml::Enums` constant with
+    # its allowed values.
+    class EnumsCommand < Command
+      def run(_options = {})
+        Chemicalml::Cml::Enums.constants(false).sort.each do |name|
+          values = Chemicalml::Cml::Enums.const_get(name)
+          puts "#{name} (#{values.size}): #{values.to_a.sort.first(20).join(', ')}"
+        end
+        0
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/info_command.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml info <element>` — show details about a CML element
+    # by XML name: Ruby class, role, attributes, applicable constraints.
+    class InfoCommand < Command
+      def run(options)
+        name = options[:element]
+        unless name
+          logger.error 'info requires an <element-name> argument (e.g. "atom")'
+          return 2
+        end
+
+        klass = Chemicalml::Cml.for_xml_name(name)
+        unless klass
+          stderr "unknown element: #{name}"
+          return 2
+        end
+
+        Chemicalml::Cml::Schema3::Configuration.ensure_registered!
+        puts "Element: <#{name}>"
+        puts "Class:   #{klass}"
+        role = role_of(klass)
+        puts "Role:    #{role || '(none)'}"
+        puts ''
+        puts "Attributes (#{klass.attributes.size}):"
+        klass.attributes.each_value do |attr|
+          col = attr.collection? ? '[]' : ' '
+          puts "  #{attr.name}#{col}"
+        end
+        applicable = constraints_for_role(role)
+        return 0 if applicable.empty?
+
+        puts ''
+        puts "Applicable constraints (#{applicable.size}):"
+        applicable.each do |(conv, c)|
+          puts "  [#{conv.qname}] #{c.name.split('::').last}"
+        end
+        0
+      end
+
+      private
+
+      def role_of(klass)
+        # Find the most specific Role module included in klass
+        # (the one with the longest name that matches Cml::Role::*).
+        klass.ancestors.find do |a|
+          next false unless a.is_a?(Module)
+          next false unless a.name
+
+          a.name.start_with?('Chemicalml::Cml::Role::')
+        end
+      end
+
+      def constraints_for_role(role)
+        return [] unless role
+
+        Chemicalml::Convention::Registry.each_constraint.with_object([]) do |(conv, c), acc|
+          roles = c.applies_to_roles
+          next if roles.nil?
+
+          matched = roles.any? do |r|
+            role <= r
+          rescue StandardError
+            false
+          end
+          next unless matched
+
+          acc << [conv, c]
+        end
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/inspect_command.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml inspect <file>` — print a tree-style summary of
+    # the document: element names, ids, nested children.
+    class InspectCommand < Command
+      def run(options)
+        path = options[:file]
+        unless path
+          logger.error 'inspect requires a <file> argument'
+          return 2
+        end
+
+        doc = Chemicalml.parse(File.read(path), schema: :schema3)
+        print_tree(doc, 0)
+        0
+      rescue ArgumentError, Lutaml::Model::InvalidFormatError => e
+        logger.error "FAIL: #{e.message}"
+        2
+      end
+
+      private
+
+      def print_tree(node, depth, max_depth: 6)
+        return if depth > max_depth
+        return unless node.is_a?(Lutaml::Model::Serializable)
+
+        indent = '  ' * depth
+        line = "#{indent}#{node.class.name.split('::').last}"
+        line += " [#{node.node_id}]" if node.is_a?(Chemicalml::Cml::Visitable) && node.node_id
+        puts line
+        return unless node.is_a?(Chemicalml::Cml::Visitable)
+
+        node.wire_children.each { |c| print_tree(c, depth + 1, max_depth: max_depth) }
+      end
+    end
+  end
+end

data/lib/chemicalml/cli/validate_command.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Cli
+    # `chemicalml validate <file>` — auto-detect convention and
+    # print violations. With `--json` / `-j`, emits machine-readable
+    # JSON.
+    class ValidateCommand < Command
+      def run(options)
+        path = options[:file]
+        unless path
+          logger.error 'validate requires a <file> argument'
+          return 2
+        end
+
+        logger.info "Validating #{path}" unless options[:json]
+        doc = Chemicalml.parse(File.read(path), schema: :schema3)
+        report = Chemicalml.validate(doc)
+
+        if options[:json]
+          puts json_report(report, path)
+        elsif report.ok? && !report.has_warnings?
+          logger.info "OK: #{path}"
+        else
+          logger.error report.summary
+        end
+        report.ok? ? 0 : 1
+      rescue ArgumentError, Lutaml::Model::InvalidFormatError => e
+        logger.error "FAIL: #{e.message}"
+        2
+      end
+
+      private
+
+      def json_report(report, path)
+        require 'json'
+        payload = {
+          file: path,
+          ok: report.ok?,
+          has_warnings: report.has_warnings?,
+          violations: report.violations.map do |v|
+            {
+              severity: v.severity,
+              path: v.path,
+              message: v.message,
+              value: v.value
+            }.compact
+          end
+        }
+        JSON.pretty_generate(payload)
+      end
+    end
+  end
+end

data/lib/chemicalml/cli.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  # Command-line interface. Built on Thor for dispatch; each command is
+  # a dedicated class under `Chemicalml::Cli::*Command` exposing
+  # `.run(args, options)` (and `#run` on an instance).
+  #
+  # Dispatch flow:
+  #
+  #   exe/chemicalml ARGV
+  #     -> Chemicalml::Cli::Base.start(ARGV)  (Thor)
+  #     -> Chemicalml::Cli::<Name>Command.new.run(args, options)
+  #
+  # Adding a new command:
+  #   1. Create `lib/chemicalml/cli/<name>_command.rb` with a class
+  #      extending `Chemicalml::Cli::Command` and implementing `#run`.
+  #   2. Add one `desc + def` block in `Chemicalml::Cli::Base` that
+  #      invokes `<Name>Command.new.run(args, options)`.
+  #   3. Add the autoload entry below.
+  module Cli
+    autoload :Base,           'chemicalml/cli/base'
+    autoload :Command,        'chemicalml/cli/command'
+    autoload :ValidateCommand,    'chemicalml/cli/validate_command'
+    autoload :InspectCommand,     'chemicalml/cli/inspect_command'
+    autoload :ConventionsCommand, 'chemicalml/cli/conventions_command'
+    autoload :DictionariesCommand, 'chemicalml/cli/dictionaries_command'
+    autoload :ElementsCommand,    'chemicalml/cli/elements_command'
+    autoload :ConstraintsCommand, 'chemicalml/cli/constraints_command'
+    autoload :EnumsCommand,       'chemicalml/cli/enums_command'
+    autoload :InfoCommand,        'chemicalml/cli/info_command'
+
+    # Backward-compatible entry point used by `exe/chemicalml` and tests.
+    # @param argv [Array<String>] the command line.
+    # @return [Integer] process exit code.
+    def self.run(argv)
+      Base.start(argv)
+      0
+    rescue StandardError => e
+      warn "FAIL: #{e.message}"
+      2
+    end
+  end
+end

data/lib/chemicalml/cml/base/abundance.rb

@@ -7,6 +7,7 @@ module Chemicalml
         def self.included(klass)
           klass.class_eval do
             include Chemicalml::Cml::Role::Abundance
+
             attribute :id, :string
             attribute :title, :string
             attribute :dict_ref, :string
@@ -17,14 +18,23 @@ module Chemicalml
             attribute :units, :string
             xml do
               namespace Chemicalml::Cml::Namespace
-              root "abundance"
-              map_attribute "id", to: :id
-              map_attribute "title", to: :title
-              map_attribute "dictRef", to: :dict_ref
-              map_attribute "convention", to: :convention
-              map_attribute "min", to: :min
-              map_attribute "max", to: :max
-              map_attribute "units", to: :units
+              root 'abundance'
+              map_attribute 'id', to: :id
+              map_attribute 'title', to: :title
+              map_attribute 'dictRef', to: :dict_ref
+              map_attribute 'convention', to: :convention
+              map_attribute 'min', to: :min
+              map_attribute 'max', to: :max
+              map_attribute 'units', to: :units
+            end
+            key_value do
+              map 'id', to: :id
+              map 'title', to: :title
+              map 'dictRef', to: :dict_ref
+              map 'convention', to: :convention
+              map 'min', to: :min
+              map 'max', to: :max
+              map 'units', to: :units
             end
           end
         end

data/lib/chemicalml/cml/base/action.rb

@@ -7,6 +7,7 @@ module Chemicalml
         def self.included(klass)
           klass.class_eval do
             include Chemicalml::Cml::Role::Action
+
             attribute :id, :string
             attribute :title, :string
             attribute :dict_ref, :string
@@ -25,22 +26,39 @@ module Chemicalml
             attribute :ref, :string
             xml do
               namespace Chemicalml::Cml::Namespace
-              root "action"
-              map_attribute "id", to: :id
-              map_attribute "title", to: :title
-              map_attribute "dictRef", to: :dict_ref
-              map_attribute "convention", to: :convention
-              map_attribute "order", to: :order
-              map_attribute "units", to: :units
-              map_attribute "start", to: :start
-              map_attribute "startCondition", to: :start_condition
-              map_attribute "duration", to: :duration
-              map_attribute "end", to: :end
-              map_attribute "endCondition", to: :end_condition
-              map_attribute "type", to: :type
-              map_attribute "actionOrder", to: :action_order
-              map_attribute "count", to: :count
-              map_attribute "ref", to: :ref
+              root 'action'
+              map_attribute 'id', to: :id
+              map_attribute 'title', to: :title
+              map_attribute 'dictRef', to: :dict_ref
+              map_attribute 'convention', to: :convention
+              map_attribute 'order', to: :order
+              map_attribute 'units', to: :units
+              map_attribute 'start', to: :start
+              map_attribute 'startCondition', to: :start_condition
+              map_attribute 'duration', to: :duration
+              map_attribute 'end', to: :end
+              map_attribute 'endCondition', to: :end_condition
+              map_attribute 'type', to: :type
+              map_attribute 'actionOrder', to: :action_order
+              map_attribute 'count', to: :count
+              map_attribute 'ref', to: :ref
+            end
+            key_value do
+              map 'id', to: :id
+              map 'title', to: :title
+              map 'dictRef', to: :dict_ref
+              map 'convention', to: :convention
+              map 'order', to: :order
+              map 'units', to: :units
+              map 'start', to: :start
+              map 'startCondition', to: :start_condition
+              map 'duration', to: :duration
+              map 'end', to: :end
+              map 'endCondition', to: :end_condition
+              map 'type', to: :type
+              map 'actionOrder', to: :action_order
+              map 'count', to: :count
+              map 'ref', to: :ref
             end
           end
         end

data/lib/chemicalml/cml/base/action_list.rb

@@ -7,13 +7,14 @@ module Chemicalml
         def self.included(klass)
           klass.class_eval do
             include Chemicalml::Cml::Role::ActionList
+
             attribute :id, :string
             attribute :title, :string
             attribute :dict_ref, :string
             attribute :convention, :string
             attribute :order, :string
 
-                        attribute :actions, :action, collection: true
+            attribute :actions, :action, collection: true
 
             attribute :start, :string
             attribute :start_condition, :string
@@ -26,22 +27,39 @@ module Chemicalml
             attribute :action_order, :string
             xml do
               namespace Chemicalml::Cml::Namespace
-              map_element "action", to: :actions
-              root "actionList"
-              map_attribute "id", to: :id
-              map_attribute "title", to: :title
-              map_attribute "dictRef", to: :dict_ref
-              map_attribute "convention", to: :convention
-              map_attribute "order", to: :order
-              map_attribute "start", to: :start
-              map_attribute "startCondition", to: :start_condition
-              map_attribute "duration", to: :duration
-              map_attribute "end", to: :end
-              map_attribute "endCondition", to: :end_condition
-              map_attribute "units", to: :units
-              map_attribute "count", to: :count
-              map_attribute "type", to: :type
-              map_attribute "actionOrder", to: :action_order
+              map_element 'action', to: :actions
+              root 'actionList'
+              map_attribute 'id', to: :id
+              map_attribute 'title', to: :title
+              map_attribute 'dictRef', to: :dict_ref
+              map_attribute 'convention', to: :convention
+              map_attribute 'order', to: :order
+              map_attribute 'start', to: :start
+              map_attribute 'startCondition', to: :start_condition
+              map_attribute 'duration', to: :duration
+              map_attribute 'end', to: :end
+              map_attribute 'endCondition', to: :end_condition
+              map_attribute 'units', to: :units
+              map_attribute 'count', to: :count
+              map_attribute 'type', to: :type
+              map_attribute 'actionOrder', to: :action_order
+            end
+            key_value do
+              map 'action', to: :actions
+              map 'id', to: :id
+              map 'title', to: :title
+              map 'dictRef', to: :dict_ref
+              map 'convention', to: :convention
+              map 'order', to: :order
+              map 'start', to: :start
+              map 'startCondition', to: :start_condition
+              map 'duration', to: :duration
+              map 'end', to: :end
+              map 'endCondition', to: :end_condition
+              map 'units', to: :units
+              map 'count', to: :count
+              map 'type', to: :type
+              map 'actionOrder', to: :action_order
             end
           end
         end