labimotion 2.3.0 → 2.4.0.rc11

data/lib/labimotion/libs/linked_element.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+module Labimotion
+  # Resolves the "inline attributes" of an element linked from a generic
+  # drag_element field.
+  #
+  # A drag_element link target is identified by the stored value's +el_klass+:
+  #   * a generic element klass name  -> the target is a Labimotion::Element and
+  #     its selectable attributes are its own property fields (layer + field);
+  #   * a permit-target key (reaction, sample, molecule, wellplate, screen,
+  #     research_plan, device_description, cell_line) -> the target is a standard
+  #     ELN model and its selectable attributes are a curated set of database columns.
+  #
+  # Used both to list the attributes a user can pick (#available) and to refresh
+  # the current values of a previously stored selection (#resolve).
+  class LinkedElement
+    SOURCE_PROPERTY = 'property'
+    SOURCE_COLUMN = 'column'
+
+    # Marks an attribute injected from the user's stored default rather than
+    # picked on this element. Stripped again before properties are persisted, so
+    # a default never silently becomes an explicit per-instance selection.
+    IS_DEFAULT = 'is_default'
+
+    # el_klass (permit-target key) => model class name
+    MODELS = {
+      'reaction' => '::Reaction',
+      'sample' => '::Sample',
+      'molecule' => '::Molecule',
+      'wellplate' => '::Wellplate',
+      'screen' => '::Screen',
+      'research_plan' => '::ResearchPlan',
+      'device_description' => '::DeviceDescription',
+      'cell_line' => '::CelllineSample'
+    }.freeze
+
+    # Display names for the above, for screens that list the linkable types.
+    PERMIT_TARGET_LABELS = {
+      'reaction' => 'Reaction', 'sample' => 'Sample', 'molecule' => 'Molecule',
+      'wellplate' => 'Wellplate', 'screen' => 'Screen', 'research_plan' => 'Research Plan',
+      'device_description' => 'Device Description', 'cell_line' => 'Cell Line'
+    }.freeze
+
+    # Curated, scalar columns exposed per type: [column/method, label, unit_column?]
+    COLUMNS = {
+      'reaction' => [
+        %w[name Name], %w[short_label], ['status', 'Status'], ['role', 'Role'],
+        ['rxno', 'Reaction Type'], ['conditions', 'Conditions'],
+        ['duration', 'Duration'], %w[solvent Solvent]
+      ],
+      'sample' => [
+        %w[name Name], %w[short_label], ['external_label', 'External Label'],
+        ['sum_formula', 'Sum Formula'], ['molecular_mass', 'Molecular Mass'],
+        %w[purity Purity], %w[density Density],
+        ['real_amount_value', 'Real Amount', 'real_amount_unit'],
+        ['target_amount_value', 'Target Amount', 'target_amount_unit'],
+        %w[location Location]
+      ],
+      'molecule' => [
+        ['iupac_name', 'IUPAC Name'], ['sum_formular', 'Sum Formula'],
+        ['molecular_weight', 'Molecular Weight'],
+        ['exact_molecular_weight', 'Exact Molecular Weight'],
+        ['cano_smiles', 'Canonical SMILES'], ['melting_point', 'Melting Point'],
+        ['boiling_point', 'Boiling Point'], %w[density Density]
+      ],
+      'wellplate' => [
+        %w[name Name], %w[short_label], ['description', 'Description'],
+        %w[width Width], %w[height Height]
+      ],
+      'screen' => [
+        %w[name Name], ['description', 'Description'], %w[result Result],
+        %w[collaborator Collaborator], ['conditions', 'Conditions'],
+        %w[requirements Requirements]
+      ],
+      'research_plan' => [
+        %w[name Name], %w[short_label]
+      ],
+      'device_description' => [
+        %w[name Name], %w[short_label], ['serial_number', 'Serial Number'],
+        ['device_class', 'Device Class'], ['operation_mode', 'Operation Mode'],
+        ['application_name', 'Application Name'], ['vendor_url', 'Vendor URL'],
+        %w[institute Institute], %w[building Building], %w[room Room]
+      ],
+      'cell_line' => [
+        ['material_name', 'Cell line name'], ['name', 'Name of specific sample'],
+        %w[short_label], %w[description Description],
+        %w[amount Amount unit], %w[passage Passage],
+        %w[contamination Contamination]
+      ]
+    }.freeze
+
+    # Property field types whose value is a scalar worth surfacing inline.
+    PROPERTY_TYPES = %w[
+      text textarea number integer select select-multi checkbox
+      datetime system-defined formula-field text-formula ontology-select
+    ].freeze
+
+    def initialize(el_klass, el_id, el_type = nil)
+      @el_klass = el_klass.to_s
+      @el_type = el_type.to_s
+      @el_id = el_id
+    end
+
+    # drag_element keeps the linked class in +el_klass+; drag_sample / drag_molecule
+    # keep it in +el_type+ (and may omit el_klass). Resolve one effective dispatch key.
+    def target_key
+      return @target_key if defined?(@target_key)
+
+      @target_key =
+        if MODELS.key?(@el_klass) || generic_klass?(@el_klass)
+          @el_klass
+        elsif MODELS.key?(@el_type)
+          @el_type
+        else
+          ''
+        end
+    end
+
+    def column_based?
+      MODELS.key?(target_key)
+    end
+
+    def generic?
+      generic_klass?(target_key)
+    end
+
+    def record
+      return @record if defined?(@record)
+
+      @record =
+        if column_based?
+          MODELS[target_key].safe_constantize&.find_by(id: @el_id)
+        elsif generic?
+          Labimotion::Element.find_by(id: @el_id)
+        end
+    end
+
+    # All attributes the user can pick, each with its current value.
+    def available
+      return generic_attributes if generic?
+      return column_attributes if column_based?
+
+      []
+    end
+
+    # Refresh the values/labels of a previously stored selection. Selections whose
+    # source attribute no longer exists are kept but flagged as missing; for an
+    # unknown/unsupported el_klass the selection is returned untouched.
+    def resolve(selected)
+      return selected unless selected.is_a?(Array)
+      return selected unless generic? || column_based?
+
+      index = available.index_by { |a| [a['source'], a['key']] }
+      selected.map do |attr|
+        next attr unless attr.is_a?(Hash)
+
+        index[[attr['source'], attr['key']]] || attr.merge('value' => nil, 'missing' => true)
+      end
+    end
+
+    # The attributes a user can pick for a klass with no element instance to read
+    # values from — the settings screen picks defaults before any link exists.
+    # Same shape as #available, minus 'value'/'value_system'.
+    def self.available_for_klass(el_klass)
+      el_klass = el_klass.to_s
+      return column_attributes_for_klass(el_klass) if MODELS.key?(el_klass)
+
+      klass = Labimotion::ElementKlass.find_by(name: el_klass)
+      klass.present? ? property_attributes_for_klass(klass) : []
+    end
+
+    # Remove attributes injected from a user's default (marked IS_DEFAULT by
+    # PropertiesEntity) from a properties hash on its way to the database. They
+    # are display-only: persisting them would freeze today's default into the
+    # element as an explicit per-instance selection, and a later change to the
+    # default would then stop reaching this link.
+    def self.strip_defaults(properties)
+      layers = properties.is_a?(Hash) ? properties[Labimotion::Prop::LAYERS] : nil
+      return properties unless layers.is_a?(Hash)
+
+      layers.each_value do |layer|
+        fields = layer.is_a?(Hash) ? layer[Labimotion::Prop::FIELDS] : nil
+        next unless fields.is_a?(Array)
+
+        fields.each { |field| strip_field_defaults(field) }
+      end
+      properties
+    end
+
+    def self.strip_field_defaults(field)
+      value = field.is_a?(Hash) ? field['value'] : nil
+      return unless value.is_a?(Hash)
+
+      attrs = value['el_attrs']
+      return unless attrs.is_a?(Array)
+
+      kept = attrs.reject { |attr| default_attr?(attr) }
+      return if kept.size == attrs.size # nothing injected — an explicit selection stays put
+
+      if kept.empty?
+        # Drop the key entirely so the field reads as "never picked" again and
+        # keeps following the user's default.
+        value.delete('el_attrs')
+      else
+        value['el_attrs'] = kept
+      end
+    end
+    private_class_method :strip_field_defaults
+
+    def self.default_attr?(attr)
+      attr.is_a?(Hash) && attr[IS_DEFAULT] == true
+    end
+    private_class_method :default_attr?
+
+    # The standard ELN types a drag field can link, for a settings screen that has
+    # to enumerate them. MODELS is the authority here, not the wider permit-target
+    # list: 'element' and 'generic_grid' are permit targets but not linkable types.
+    def self.permit_targets
+      MODELS.keys.map { |key| { 'key' => key, 'label' => PERMIT_TARGET_LABELS[key] || key.humanize } }
+    end
+
+    # Read off the released template rather than an instance, so the list matches
+    # what every element of the klass actually has.
+    def self.property_attributes_for_klass(klass)
+      layers = (klass.properties_release || {})[Labimotion::Prop::LAYERS] || {}
+      ordered = layers.values.sort_by { |layer| layer['position'] || 0 }
+      ordered.flat_map { |layer| layer_property_attributes(layer) }
+    end
+    private_class_method :property_attributes_for_klass
+
+    def self.layer_property_attributes(layer)
+      (layer[Labimotion::Prop::FIELDS] || []).filter_map do |field|
+        klass_property_attribute(layer, field) if PROPERTY_TYPES.include?(field['type'])
+      end
+    end
+    private_class_method :layer_property_attributes
+
+    def self.klass_property_attribute(layer, field)
+      {
+        'source' => SOURCE_PROPERTY,
+        'key' => "#{layer['key']}::#{field['field']}",
+        'label' => field['label'].presence || field['field'],
+        'type' => field['type'],
+        'group' => layer['label'].presence || layer['key']
+      }
+    end
+    private_class_method :klass_property_attribute
+
+    def self.column_attributes_for_klass(el_klass)
+      (COLUMNS[el_klass] || []).map do |col, label, _unit_col|
+        {
+          'source' => SOURCE_COLUMN,
+          'key' => col,
+          'label' => label.presence || col.to_s.humanize,
+          'type' => SOURCE_COLUMN,
+          'group' => el_klass
+        }
+      end
+    end
+    private_class_method :column_attributes_for_klass
+
+    private
+
+    def generic_klass?(name)
+      name.present? && !MODELS.key?(name) && Labimotion::ElementKlass.exists?(name: name)
+    end
+
+    def generic_attributes
+      el = record
+      return [] unless el&.properties.is_a?(Hash)
+
+      attrs = []
+      layers = el.properties[Labimotion::Prop::LAYERS] || {}
+      layers.values.sort_by { |layer| layer['position'] || 0 }.each do |layer|
+        (layer[Labimotion::Prop::FIELDS] || []).each do |field|
+          next unless PROPERTY_TYPES.include?(field['type'])
+
+          attr = {
+            'source' => SOURCE_PROPERTY,
+            'key' => "#{layer['key']}::#{field['field']}",
+            'label' => field['label'].presence || field['field'],
+            'type' => field['type'],
+            'value' => field['value'],
+            'group' => layer['label'].presence || layer['key']
+          }
+          attr['value_system'] = field['value_system'] if field['value_system'].present?
+          attrs << attr
+        end
+      end
+      attrs
+    end
+
+    def column_attributes
+      rec = record
+      return [] if rec.blank?
+
+      (COLUMNS[target_key] || []).filter_map do |col, label, unit_col|
+        next unless rec.respond_to?(col)
+
+        attr = {
+          'source' => SOURCE_COLUMN,
+          'key' => col,
+          'label' => label.presence || col.to_s.humanize,
+          'type' => SOURCE_COLUMN,
+          'value' => rec.public_send(col),
+          'group' => target_key
+        }
+        attr['value_system'] = rec.public_send(unit_col) if unit_col && rec.respond_to?(unit_col) && rec.public_send(unit_col).present?
+        attr
+      end
+    end
+  end
+end

data/lib/labimotion/libs/ontology_store.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'digest'
+require 'fileutils'
+
+module Labimotion
+  # The stored vocabulary behind an "ontology-select" field: one JSON file per
+  # ontology root, holding that root's whole subtree.
+  #
+  # Both consumers read this one file. The picker renders it as a tree, the AI
+  # auto-fill takes the labels out of it. Before the store they resolved the
+  # same subtree independently — the browser walking /children node by node,
+  # the server asking for the transitive closure — so the only thing keeping
+  # the two lists in agreement was somebody checking.
+  #
+  # Nothing is ever written straight onto the live path. A concurrent reader
+  # must not see a half-written file, and a failed fetch must not replace a
+  # good list with an empty one, so a write takes a lock, validates what came
+  # back, writes a sibling temp file and renames it into place.
+  class OntologyStore
+    # Raised for anything the person who pressed Refresh should be told about.
+    class Error < StandardError; end
+    # Someone else is already refreshing this root.
+    class Busy < Error; end
+
+    # The last path segment of an IRI is the term's accession (`BAO_0000019`),
+    # which is already filename-safe and, unlike a hash, says what the file is
+    # when you list the directory. Anything that is not a clean accession —
+    # which no real IRI produces — falls back to a digest rather than being
+    # trusted into a path.
+    ACCESSION = /\A[A-Za-z0-9][A-Za-z0-9_.-]{0,63}\z/
+    # `owl_name` is not the IRI's namespace: CHMO serves OBI and BFO terms, so
+    # the accession alone is not unique across ontologies and the prefix stays.
+    ONTOLOGY = /\A[a-z0-9][a-z0-9_-]{0,31}\z/
+
+    # A refresh that comes back with a fraction of what is already stored is a
+    # service having a bad day, not an ontology that shrank by half. Keep what
+    # is on disk and say so.
+    KEEP_RATIO = 0.5
+    # Below this there is no meaningful proportion to compare against.
+    MIN_COMPARABLE = 8
+    # Refresh is a user action on shared state; this is politeness toward the
+    # ontology service, not protection of our own data.
+    MIN_REFRESH_SECONDS = 60
+
+    class << self
+      # The subtree for one parsed root, warming the file when it is missing.
+      # Never raises: a root that cannot be stored still answers this request
+      # from a live resolve, which is exactly the behaviour it had before.
+      #
+      # @param root [Hash] { ontology:, iri: } as Labimotion::OntologyTerms.parse returns
+      # @return [Hash, nil] the stored document, or nil when nothing could be had
+      def document(root, synced_by: nil)
+        stored = read(root)
+        return stored if stored
+
+        begin
+          refresh!(root, synced_by: synced_by, interval: false)
+        rescue StandardError => e
+          log("could not store #{root[:iri]}: #{e.message}")
+          live_document(root)
+        end
+      end
+
+      # Just the labels, for the auto-fill prompt.
+      def labels(root)
+        doc = document(root)
+        terms = doc.is_a?(Hash) ? doc['terms'] : nil
+        Array(terms).filter_map { |term| term['label'].to_s.strip.presence }
+      end
+
+      # Re-fetch and rewrite. Raises Error with a message meant to be shown to
+      # whoever asked for it.
+      #
+      # @param interval [Boolean] enforce MIN_REFRESH_SECONDS (user-triggered
+      #   refresh); false when warming a file that does not exist yet.
+      def refresh!(root, synced_by: nil, interval: true)
+        existing = read(root)
+        guard_interval!(existing) if interval
+
+        with_lock(root) do
+          # Re-read inside the lock: whoever held it may have just done the work.
+          fresh = read(root)
+          next fresh if interval == false && fresh
+
+          terms = Labimotion::OntologyTerms.subtree(root)
+          validate!(terms, existing)
+          doc = build_document(root, terms, synced_by)
+          write_atomically(path_for(root), doc)
+          doc
+        end
+      end
+
+      # The stored document, or nil when there is no readable file.
+      def read(root)
+        path = path_for(root)
+        return nil unless File.exist?(path)
+
+        doc = JSON.parse(File.read(path))
+        doc.is_a?(Hash) && doc['terms'].is_a?(Array) ? doc : nil
+      rescue StandardError => e
+        log("unreadable store for #{root[:iri]}: #{e.message}")
+        nil
+      end
+
+      def stored?(root)
+        File.exist?(path_for(root))
+      rescue Error
+        false
+      end
+
+      # `<ontology>-<accession>.json` under the roots directory.
+      def path_for(root)
+        path = File.join(dir, filename(root))
+        # The root comes from a template a designer controls. Taking the segment
+        # after the last separator cannot produce a traversal, but this makes it
+        # impossible for a later edit to the derivation to reintroduce one.
+        raise Error, 'refusing an ontology path outside the store' unless
+          File.expand_path(path).start_with?("#{File.expand_path(dir)}#{File::SEPARATOR}")
+
+        path
+      end
+
+      def filename(root)
+        ontology = root[:ontology].to_s
+        raise Error, "unusable ontology name #{ontology.inspect}" unless ONTOLOGY.match?(ontology)
+
+        iri = root[:iri].to_s
+        "#{ontology}-#{accession(iri) || "x#{Digest::SHA256.hexdigest(iri)[0, 16]}"}.json"
+      end
+
+      # Read through a method so a spec can stub the constant.
+      def dir
+        Labimotion::ONTOLOGY_ROOTS_DIR
+      end
+
+      private
+
+      def accession(iri)
+        tail = iri.split(%r{[#/]}).last.to_s
+        ACCESSION.match?(tail) ? tail : nil
+      end
+
+      # Resolved but deliberately not written — used when the file cannot be
+      # created (directory unwritable, another process holding the lock) so the
+      # caller still gets an answer.
+      def live_document(root)
+        terms = Labimotion::OntologyTerms.subtree(root)
+        return nil if terms.empty?
+
+        build_document(root, terms, nil)
+      rescue StandardError => e
+        log("live resolve failed for #{root[:iri]}: #{e.message}")
+        nil
+      end
+
+      def build_document(root, terms, synced_by)
+        {
+          'ontology' => root[:ontology].to_s,
+          'iri' => root[:iri].to_s,
+          'source' => Labimotion::OntologyTerms.base_url,
+          'synced_at' => Time.now.utc.iso8601,
+          'synced_by' => synced_by.presence,
+          'count' => terms.size,
+          'terms' => terms
+        }
+      end
+
+      def validate!(terms, existing)
+        raise Error, 'the ontology service returned no terms for this root' if terms.blank?
+
+        previous = existing.is_a?(Hash) ? existing['terms'] : nil
+        return unless previous.is_a?(Array) && previous.size >= MIN_COMPARABLE
+        return if terms.size >= (previous.size * KEEP_RATIO)
+
+        raise Error, "refusing the update: #{terms.size} terms where #{previous.size} were stored"
+      end
+
+      def guard_interval!(existing)
+        synced_at = existing.is_a?(Hash) ? existing['synced_at'] : nil
+        return if synced_at.blank?
+
+        age = Time.now.utc - Time.parse(synced_at.to_s).utc
+        return if age >= MIN_REFRESH_SECONDS
+
+        raise Error, "this ontology was refreshed #{age.round} s ago; try again in a moment"
+      rescue ArgumentError
+        nil # An unparseable stamp is not a reason to refuse a refresh.
+      end
+
+      def with_lock(root)
+        FileUtils.mkdir_p(dir)
+        File.open("#{path_for(root)}.lock", File::RDWR | File::CREAT, 0o644) do |lock|
+          raise Busy, 'a refresh for this ontology is already running' unless
+            lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+          begin
+            yield
+          ensure
+            lock.flock(File::LOCK_UN)
+          end
+        end
+      end
+
+      # Rename is atomic within a filesystem; writing onto the live path is not,
+      # and a reader landing mid-write gets a JSON parse error for their trouble.
+      def write_atomically(path, doc)
+        tmp = "#{path}.tmp.#{Process.pid}"
+        begin
+          File.write(tmp, JSON.generate(doc))
+          File.rename(tmp, path)
+        ensure
+          FileUtils.rm_f(tmp)
+        end
+      end
+
+      def log(message)
+        Labimotion.logger.warn("OntologyStore #{message}")
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end