openehr 1.3.0 → 2.0.0

data/lib/openehr/aql/engine/contains_resolver.rb

@@ -0,0 +1,161 @@
+require_relative 'binding'
+
+module OpenEHR
+  module AQL
+    # Walks a FromClause's containment tree against a Dataset, producing
+    # one Binding per match.
+    #
+    # An EHR root variable (bound to the Dataset::EHRRecord itself - not
+    # an OpenEHR::RM::EHR::EHR - since a Dataset element doesn't have to
+    # carry one; see Dataset's own header comment), a right-recursive
+    # CONTAINS chain searching a matched Locatable's *entire* subtree
+    # (any depth, via Pathable#path_children) for the next class,
+    # archetype-predicate filtering, AND/OR-grouped sibling branches
+    # (cross-product / union of each branch's matches) and NOT CONTAINS
+    # (parent matches survive only when the negated class is absent).
+    # standardPredicate/nodePredicate filtering and an EHR-level
+    # predicate (e.g. "[ehr_id/value=$ehr_id]") are added by a later
+    # engine milestone.
+    class ContainsResolver
+      def initialize(from_clause, dataset)
+        @root = from_clause.containment
+        @dataset = dataset
+      end
+
+      def each_binding
+        return enum_for(:each_binding) unless block_given?
+
+        @dataset.each_ehr do |ehr_record|
+          resolve(@root, ehr_record, ehr_record.compositions).each do |variables, _bound|
+            yield Binding.new(ehr_record: ehr_record, variables: variables)
+          end
+        end
+      end
+
+      private
+
+      # Returns an Array of [variables_hash, bound_object] pairs. `pool`
+      # is the Enumerable of Pathable candidates in scope for this node:
+      # an EHR record's top-level compositions at the root, or a parent
+      # match's full recursive descendant set below a CONTAINS.
+      # `bound_object` lets the caller (a further CONTAINS) compute the
+      # next-level pool from wherever this node ended up.
+      def resolve(node, ehr_record, pool)
+        case node
+        when Model::ClassExpression
+          resolve_class_expression(node, ehr_record, pool)
+        when Model::Containment
+          resolve_containment(node, ehr_record, pool)
+        when Model::ContainmentAnd
+          resolve_containment_and(node, ehr_record, pool)
+        when Model::ContainmentOr
+          resolve_containment_or(node, ehr_record, pool)
+        else
+          raise ExecutionError, "cannot execute a #{node.class} containment yet"
+        end
+      end
+
+      def resolve_class_expression(class_expression, ehr_record, pool)
+        return [[variables_for(class_expression, ehr_record), ehr_record]] if ehr_root?(class_expression)
+
+        pool.select { |candidate| matches?(candidate, class_expression) }
+            .map { |candidate| [variables_for(class_expression, candidate), candidate] }
+      end
+
+      def resolve_containment(containment, ehr_record, pool)
+        parent_matches = resolve(containment.parent, ehr_record, pool)
+        return negated_matches(containment, ehr_record, parent_matches) if containment.negated
+
+        parent_matches.flat_map do |parent_vars, parent_obj|
+          resolve(containment.child, ehr_record, descendant_pool(parent_obj, ehr_record)).map do |child_vars, child_obj|
+            [parent_vars.merge(child_vars), child_obj]
+          end
+        end
+      end
+
+      # "A NOT CONTAINS B": a parent match survives only when B has no
+      # match anywhere in that parent's subtree. B never binds a
+      # variable (there's nothing to bind an absence to).
+      def negated_matches(containment, ehr_record, parent_matches)
+        parent_matches.select do |_parent_vars, parent_obj|
+          resolve(containment.child, ehr_record, descendant_pool(parent_obj, ehr_record)).empty?
+        end
+      end
+
+      # "A CONTAINS (B AND C)": both branches must match somewhere in
+      # the same pool; every combination of a B-match and a C-match
+      # becomes its own binding (AQL has no correlation between sibling
+      # branches beyond sharing a parent).
+      def resolve_containment_and(node, ehr_record, pool)
+        left_matches = resolve(node.left, ehr_record, pool)
+        return [] if left_matches.empty?
+
+        right_matches = resolve(node.right, ehr_record, pool)
+        return [] if right_matches.empty?
+
+        left_matches.flat_map do |left_vars, _left_obj|
+          right_matches.map { |right_vars, right_obj| [left_vars.merge(right_vars), right_obj] }
+        end
+      end
+
+      # "A CONTAINS (B OR C)": either branch matching is enough; each
+      # branch's matches contribute their own bindings independently.
+      def resolve_containment_or(node, ehr_record, pool)
+        resolve(node.left, ehr_record, pool) + resolve(node.right, ehr_record, pool)
+      end
+
+      def descendant_pool(bound_object, ehr_record)
+        return ehr_record.compositions if bound_object.equal?(ehr_record)
+
+        descendants_of(bound_object)
+      end
+
+      # A subtree walk (any depth) over Pathable#path_children, matching
+      # real AQL CONTAINS semantics ("anywhere below", not just direct
+      # children).
+      def descendants_of(root)
+        results = []
+        queue = child_values(root)
+        until queue.empty?
+          node = queue.shift
+          next unless node.is_a?(OpenEHR::RM::Common::Archetyped::Pathable)
+
+          results << node
+          queue.concat(child_values(node))
+        end
+        results
+      end
+
+      def child_values(node)
+        node.path_children.values.flat_map { |value| value.is_a?(Array) ? value : [value] }
+      end
+
+      def matches?(candidate, class_expression)
+        return false unless OpenEHR::RM.subtype_of?(candidate, class_expression.class_name)
+
+        predicate_matches?(candidate, class_expression.predicate)
+      end
+
+      def predicate_matches?(candidate, predicate)
+        case predicate
+        when nil
+          true
+        when Model::ArchetypePredicate
+          candidate.respond_to?(:archetype_node_id) && candidate.archetype_node_id == predicate.archetype_id
+        else
+          raise ExecutionError, "cannot evaluate a #{predicate.class} predicate yet"
+        end
+      end
+
+      def variables_for(class_expression, matched)
+        return {} unless class_expression.variable
+
+        { class_expression.variable => matched }
+      end
+
+      def ehr_root?(class_expression)
+        class_expression.class_name.upcase == 'EHR'
+      end
+    end
+  end
+end

data/lib/openehr/aql/engine/dataset.rb

@@ -0,0 +1,122 @@
+require_relative '../errors'
+
+# OpenEHR::AQL::Dataset is the AQL engine's only input boundary, and the
+# whole of its framework/ORM independence: everything under
+# lib/openehr/aql/ talks to "wherever your data lives" exclusively
+# through this class, which itself talks to nothing but the Ruby
+# `Enumerable`/`#each` protocol and this gem's own RM classes. No
+# ActiveRecord/Rails/Sequel/etc. is required or referenced anywhere
+# here or downstream - see the project plan's "Dataset:
+# フレームワーク/ORM非依存の契約" section for the full design rationale.
+#
+# Construction is cheap and never iterates its source (laziness is
+# preserved end to end); each element is normalized into an EHRRecord
+# only as #each_ehr actually walks it.
+#
+#   Dataset.new(ehrs:)                       # ehrs: anything #each-able
+#   Dataset.of_compositions(compositions, ehr_id: nil)
+#   Dataset.wrap(source)                     # Dataset / Composition-Enumerable / EHR-shaped-Enumerable
+#
+# Each element of `ehrs:` must be one of:
+#   - a Hash (symbol or string keys): {ehr_id:, compositions:, ehr_status: (optional)}
+#   - a duck-typed object responding to #ehr_id / #compositions (/ #ehr_status)
+#   - a full OpenEHR::RM::EHR::EHR (unwrapped via ehr_id.value,
+#     compositions.map { |vc| vc.latest_version.data }, and
+#     ehr_status.latest_version.data)
+#
+# Every element yielded by a record's compositions MUST be
+# is_a?(OpenEHR::RM::Common::Archetyped::Pathable) - anything else
+# raises DatasetError immediately, naming the offending class and
+# index. This is the deliberate anti-leak mechanism that keeps loose
+# ActiveRecord rows (or any other non-RM object) from half-working via
+# accidental duck typing.
+module OpenEHR
+  module AQL
+    class Dataset
+      EHRRecord = Struct.new(:ehr_id, :ehr, :ehr_status, :compositions, keyword_init: true)
+
+      def self.of_compositions(compositions, ehr_id: nil)
+        new(ehrs: [{ ehr_id: ehr_id, compositions: compositions }])
+      end
+
+      def self.wrap(source)
+        return source if source.is_a?(Dataset)
+
+        unless source.is_a?(Enumerable)
+          raise DatasetError, "cannot build a Dataset from a #{source.class} (expected a Dataset or an Enumerable)"
+        end
+
+        first, rest = source.first, source
+        return of_compositions(rest) if first.is_a?(OpenEHR::RM::Common::Archetyped::Pathable)
+
+        new(ehrs: rest)
+      end
+
+      def initialize(ehrs:)
+        @ehrs = ehrs
+      end
+
+      def each_ehr
+        return enum_for(:each_ehr) unless block_given?
+
+        @ehrs.each { |element| yield normalize(element) }
+      end
+
+      private
+
+      def normalize(element)
+        return from_ehr(element) if element.is_a?(OpenEHR::RM::EHR::EHR)
+        return from_hash(element) if element.is_a?(Hash)
+
+        from_record(element)
+      end
+
+      def from_hash(hash)
+        stringified = hash.transform_keys(&:to_s)
+        build_record(
+          ehr_id: stringified['ehr_id'],
+          ehr: nil,
+          ehr_status: stringified['ehr_status'],
+          compositions: stringified['compositions']
+        )
+      end
+
+      def from_record(record)
+        build_record(
+          ehr_id: record.ehr_id,
+          ehr: nil,
+          ehr_status: record.respond_to?(:ehr_status) ? record.ehr_status : nil,
+          compositions: record.compositions
+        )
+      end
+
+      def from_ehr(ehr)
+        build_record(
+          ehr_id: ehr.ehr_id,
+          ehr: ehr,
+          ehr_status: ehr.ehr_status&.latest_version&.data,
+          compositions: ehr.compositions.map { |versioned_composition| versioned_composition.latest_version.data }
+        )
+      end
+
+      def build_record(ehr_id:, ehr:, ehr_status:, compositions:)
+        compositions = Array(compositions)
+        compositions.each_with_index do |composition, index|
+          next if composition.is_a?(OpenEHR::RM::Common::Archetyped::Pathable)
+
+          raise DatasetError,
+                "Dataset compositions must be OpenEHR::RM RM objects (Pathable), " \
+                "got #{composition.class} at index #{index}"
+        end
+
+        EHRRecord.new(ehr_id: unwrap_id(ehr_id), ehr: ehr, ehr_status: ehr_status, compositions: compositions)
+      end
+
+      def unwrap_id(id)
+        return nil if id.nil?
+
+        id.respond_to?(:value) ? id.value : id
+      end
+    end
+  end
+end

data/lib/openehr/aql/engine/path_evaluator.rb

@@ -0,0 +1,137 @@
+module OpenEHR
+  module AQL
+    # Evaluates a columnExpr/terminal Model node against a Binding.
+    #
+    # SELECT paths ("o/data[at0001]/.../value/magnitude", "c/name/value")
+    # walk one segment at a time: as long as the current value is
+    # Pathable AND the segment names one of its *declared*
+    # `path_attribute`s (the content-structure attributes PATHABLE
+    # navigation was built for - see lib/openehr/rm/common/archetyped.rb),
+    # the hop goes through PATHABLE#items_at_path (reusing its predicate
+    # matching for node/archetype predicates). Everything else - RM
+    # metadata that isn't part of that DSL (name, archetype_details,
+    # composer, ...) and genuinely non-Pathable values (a DV_QUANTITY's
+    # magnitude, a DV_TEXT's value) - is a plain attribute read via a
+    # whitelisted public_send, never an arbitrary send driven by query
+    # text. A predicate directly on an identifiedPath's own variable
+    # (e.g. "c[at001]/..."), parameters and function calls are added by
+    # later engine milestones.
+    module PathEvaluator
+      # Attribute hops not reachable through the path_attribute DSL.
+      # Expand only when a real query needs another one - see the
+      # project's "no arbitrary send" rule in the class comment above.
+      ALLOWED_TERMINAL_HOPS = %w[magnitude name value].freeze
+
+      # Dataset::EHRRecord#ehr_id is already an unwrapped String (see
+      # Dataset's own header comment), but AQL's "e/ehr_id/value" syntax
+      # still expects a HierObjectID-shaped hop with its own #value -
+      # this tiny wrapper bridges that gap.
+      EhrIdValue = Struct.new(:value)
+
+      module_function
+
+      def evaluate(expression, binding)
+        case expression
+        when Model::IdentifiedPath
+          evaluate_identified_path(expression, binding)
+        when Model::Literal
+          expression.value
+        else
+          raise ExecutionError, "cannot evaluate a #{expression.class} yet"
+        end
+      end
+
+      def evaluate_identified_path(path, binding)
+        raise ExecutionError, 'predicates on a SELECT variable are not yet supported' if path.predicate
+
+        value = binding[path.variable]
+        return value unless path.path
+
+        path.path.segments.reduce(value) do |current, segment|
+          current.nil? ? nil : navigate(current, segment)
+        end
+      end
+
+      def navigate(current, segment)
+        return navigate_ehr_record(current, segment) if current.is_a?(Dataset::EHRRecord)
+
+        if declared_path_attribute?(current, segment)
+          navigate_pathable(current, segment)
+        else
+          navigate_terminal(current, segment)
+        end
+      end
+
+      # "e/ehr_id/value" and "e/ehr_status/..." always resolve (from
+      # Dataset's own record shape); any other "e/..." path falls
+      # through to whatever full RM::EHR::EHR the record carries, if
+      # any, else resolves to nil rather than erroring - AQL's
+      # path-absent-means-null semantics again, not a missing feature.
+      def navigate_ehr_record(record, segment)
+        raise ExecutionError, "path predicates on an EHR root are not supported (#{segment.attribute})" if segment.predicate
+
+        case segment.attribute
+        when 'ehr_id' then EhrIdValue.new(record.ehr_id)
+        when 'ehr_status' then record.ehr_status
+        else
+          record.ehr.nil? ? nil : navigate(record.ehr, segment)
+        end
+      end
+
+      def declared_path_attribute?(current, segment)
+        current.is_a?(OpenEHR::RM::Common::Archetyped::Pathable) &&
+          current.class.path_attributes.map(&:to_s).include?(segment.attribute)
+      end
+
+      # A path segment matching nothing is a legitimate "no value here"
+      # (AQL's path-absent-means-null semantics, same convention as
+      # PATHABLE#item_at_path itself), not an error - only an
+      # *ambiguous* match (more than one item) is.
+      def navigate_pathable(current, segment)
+        matches = current.items_at_path(rm_path_for(segment))
+        case matches.size
+        when 0 then nil
+        when 1 then matches.first
+        else raise ExecutionError, "path segment #{segment.to_s.inspect} matched #{matches.size} items " \
+                                    '(fan-out SELECT paths are not yet supported)'
+        end
+      end
+
+      def navigate_terminal(current, segment)
+        raise ExecutionError, "path predicates on a non-Pathable value are not supported (#{segment.attribute})" if segment.predicate
+        unless ALLOWED_TERMINAL_HOPS.include?(segment.attribute)
+          raise ExecutionError, "unsupported path attribute #{segment.attribute.inspect} on a #{current.class}"
+        end
+
+        current.public_send(segment.attribute)
+      end
+
+      def rm_path_for(segment)
+        return "/#{segment.attribute}" unless segment.predicate
+
+        "/#{segment.attribute}[#{predicate_path_text(segment.predicate)}]"
+      end
+
+      def predicate_path_text(predicate)
+        case predicate
+        when Model::ArchetypePredicate
+          predicate.archetype_id
+        when Model::NodePredicate
+          node_predicate_path_text(predicate)
+        else
+          raise ExecutionError, "cannot evaluate a #{predicate.class} path predicate yet"
+        end
+      end
+
+      def node_predicate_path_text(predicate)
+        return predicate.code unless predicate.value
+
+        unless predicate.value.is_a?(String)
+          raise ExecutionError, "cannot evaluate a #{predicate.value.class} node predicate value yet"
+        end
+
+        "#{predicate.code}, '#{predicate.value}'"
+      end
+    end
+  end
+end

data/lib/openehr/aql/engine/predicate_evaluator.rb

@@ -0,0 +1,65 @@
+module OpenEHR
+  module AQL
+    # Evaluates a WHERE clause's boolean expression tree against a
+    # Binding and the query's runtime params. E5 scope: comparisons
+    # (reusing PathEvaluator for both sides), AND/OR/NOT and EXISTS.
+    # LIKE, MATCHES and functionCall operands are added by later engine
+    # milestones.
+    module PredicateEvaluator
+      COMPARATORS = {
+        '=' => :==, '!=' => :!=, '<' => :<, '<=' => :<=, '>' => :>, '>=' => :>=
+      }.freeze
+
+      module_function
+
+      # `expression` is nil when there is no WHERE clause at all.
+      def matches?(expression, binding, params)
+        case expression
+        when nil
+          true
+        when Model::Comparison
+          evaluate_comparison(expression, binding, params)
+        when Model::AndExpr
+          matches?(expression.left, binding, params) && matches?(expression.right, binding, params)
+        when Model::OrExpr
+          matches?(expression.left, binding, params) || matches?(expression.right, binding, params)
+        when Model::NotExpr
+          !matches?(expression.operand, binding, params)
+        when Model::ExistsExpr
+          !PathEvaluator.evaluate(expression.path, binding).nil?
+        else
+          raise ExecutionError, "cannot evaluate a #{expression.class} WHERE expression yet"
+        end
+      end
+
+      # A comparison against an absent (nil) value is neither true nor
+      # false in AQL/SQL terms - it simply fails to select the row, the
+      # same as SQL's NULL-comparison-is-UNKNOWN convention.
+      def evaluate_comparison(comparison, binding, params)
+        left = resolve_operand(comparison.left, binding, params)
+        right = resolve_operand(comparison.right, binding, params)
+        return false if left.nil? || right.nil?
+
+        compare(left, comparison.operator, right)
+      end
+
+      def resolve_operand(node, binding, params)
+        return lookup_param(node, params) if node.is_a?(Model::Parameter)
+
+        PathEvaluator.evaluate(node, binding)
+      end
+
+      def lookup_param(parameter, params)
+        return params[parameter.name.to_sym] if params.key?(parameter.name.to_sym)
+        return params[parameter.name] if params.key?(parameter.name)
+
+        raise UnboundParameterError, "unbound parameter: $#{parameter.name}"
+      end
+
+      def compare(left, operator, right)
+        method = COMPARATORS.fetch(operator) { raise ExecutionError, "unknown comparison operator #{operator.inspect}" }
+        left.public_send(method, right)
+      end
+    end
+  end
+end

data/lib/openehr/aql/engine.rb

@@ -0,0 +1,119 @@
+require_relative 'engine/binding'
+require_relative 'engine/contains_resolver'
+require_relative 'engine/path_evaluator'
+require_relative 'engine/predicate_evaluator'
+require_relative 'result_set'
+
+module OpenEHR
+  module AQL
+    # Orchestrates one Query execution against a Dataset, in the order
+    # CONTAINS -> WHERE -> ORDER BY -> SELECT -> DISTINCT -> LIMIT/OFFSET.
+    #
+    # A SELECT clause made entirely of aggregate columns
+    # (Model::AggregateFunctionCall) collapses the whole (post-WHERE)
+    # binding set into a single summary row instead - ORDER BY/DISTINCT/
+    # LIMIT don't apply to it, matching plain SQL aggregate-without-
+    # GROUP-BY semantics. Mixing aggregate and plain columns, and
+    # generic (non-aggregate) function calls, are not yet supported.
+    class Engine
+      def initialize(query)
+        @query = query
+      end
+
+      def execute(dataset, params: {})
+        bindings = ContainsResolver.new(@query.from_clause, Dataset.wrap(dataset)).each_binding
+                                    .select { |binding| where_matches?(binding, params) }
+        rows = aggregate_query? ? [aggregate_row(bindings)] : select_rows(bindings)
+        ResultSet.new(columns: @query.select_clause.columns.map { |column| column_name(column) }, rows: rows)
+      end
+
+      private
+
+      def where_matches?(binding, params)
+        PredicateEvaluator.matches?(@query.where_clause&.expression, binding, params)
+      end
+
+      def select_rows(bindings)
+        rows = project(order(bindings))
+        rows = rows.uniq if @query.select_clause.distinct
+        apply_limit(rows)
+      end
+
+      def order(bindings)
+        order_by = @query.order_by_clause
+        return bindings unless order_by
+
+        bindings.sort { |a, b| compare_bindings(a, b, order_by.items) }
+      end
+
+      def compare_bindings(a, b, order_by_items)
+        order_by_items.each do |item|
+          cmp = compare_values(PathEvaluator.evaluate(item.path, a), PathEvaluator.evaluate(item.path, b))
+          cmp = -cmp if item.direction == :desc
+          return cmp unless cmp.zero?
+        end
+        0
+      end
+
+      # nil (an absent path) sorts after any real value, regardless of
+      # ASC/DESC - the usual SQL "NULLS LAST" convention.
+      def compare_values(a, b)
+        return 0 if a.nil? && b.nil?
+        return 1 if a.nil?
+        return -1 if b.nil?
+
+        a <=> b
+      end
+
+      def project(bindings)
+        columns = @query.select_clause.columns
+        bindings.map { |binding| columns.map { |column| PathEvaluator.evaluate(column.expression, binding) } }
+      end
+
+      def apply_limit(rows)
+        limit_clause = @query.limit_clause
+        return rows unless limit_clause
+
+        rows.drop(limit_clause.offset).take(limit_clause.limit)
+      end
+
+      def aggregate_query?
+        @query.select_clause.columns.any? { |column| column.expression.is_a?(Model::AggregateFunctionCall) }
+      end
+
+      def aggregate_row(bindings)
+        @query.select_clause.columns.map do |column|
+          call = column.expression
+          unless call.is_a?(Model::AggregateFunctionCall)
+            raise ExecutionError, 'mixing aggregate and non-aggregate SELECT columns is not yet supported'
+          end
+
+          evaluate_aggregate(call, bindings)
+        end
+      end
+
+      def evaluate_aggregate(call, bindings)
+        return bindings.size if call.name == :count && call.path.nil?
+
+        values = bindings.map { |binding| PathEvaluator.evaluate(call.path, binding) }.compact
+        values = values.uniq if call.distinct
+
+        case call.name
+        when :count then values.size
+        when :min then values.min
+        when :max then values.max
+        when :sum then values.empty? ? nil : values.sum
+        when :avg then values.empty? ? nil : values.sum.fdiv(values.size)
+        else raise ExecutionError, "cannot evaluate a #{call.name.inspect} aggregate function yet"
+        end
+      end
+
+      def column_name(column)
+        return column.alias_name if column.alias_name
+
+        expression = column.expression
+        expression.is_a?(Model::IdentifiedPath) ? expression.variable : expression.class.name
+      end
+    end
+  end
+end

data/lib/openehr/aql/errors.rb

@@ -0,0 +1,27 @@
+# Error hierarchy for the AQL subsystem (parsing, semantic checks, and
+# execution). Kept in its own file so lexer.rb/parser.rb/engine.rb can
+# each require just this, without pulling in the rest of the subsystem.
+module OpenEHR
+  module AQL
+    class Error < StandardError; end
+
+    # Raised by the Lexer/Parser on malformed AQL source. Carries the
+    # 1-based line/column of the offending token so the message can point
+    # at the exact spot, e.g. "line 2, column 8: ...".
+    class ParseError < Error
+      attr_reader :line, :column
+
+      def initialize(message, line: nil, column: nil)
+        @line = line
+        @column = column
+        location = line && column ? " (line #{line}, column #{column})" : ''
+        super("#{message}#{location}")
+      end
+    end
+
+    class SemanticError < Error; end
+    class UnboundParameterError < Error; end
+    class ExecutionError < Error; end
+    class DatasetError < Error; end
+  end
+end