diamond-orm 0.1.0

data/lib/diamond/operators/like.rb

@@ -0,0 +1,142 @@
+module Diamond
+  module Operators
+    # LIKE operator — `where { name =~ pattern }` where pattern is a String
+    # or a Regexp.
+    #
+    # String RHS is passed through as the LIKE pattern verbatim. `%` matches
+    # any sequence, `_` matches any single char. Backslash escapes literal
+    # `%`, `_`, and `\` themselves.
+    #
+    # Regexp RHS is translated to a LIKE pattern with documented rules:
+    #
+    #   literal chars   -> literal (% and _ get backslash-escaped)
+    #   \X              -> X (with %, _, \ escaped for LIKE)
+    #   .  (unescaped)  -> _    any single char
+    #   .*              -> %    any sequence
+    #   ^   at start    -> dropped (LIKE doesn't anchor)
+    #   $   at end      -> dropped (LIKE doesn't anchor)
+    #
+    # Anything else (character classes [], alternation |, groups (), quantifiers
+    # + ? {n,m}, lookahead/lookbehind) raises ArgumentError. Honest, not magical.
+    module Like
+      PRIORITY = 60
+
+      def self.priority
+        PRIORITY
+      end
+
+      def self.parse_where(node, schema)
+        return nil unless node.is_a?(Prism::CallNode)
+        return nil unless node.name == :=~
+        return nil unless node.receiver
+        return nil unless node.arguments
+        return nil unless node.arguments.arguments.size == 1
+
+        rhs_node = node.arguments.arguments.first
+        pattern =
+          case rhs_node
+          when Prism::StringNode
+            rhs_node.unescaped
+          when Prism::RegularExpressionNode
+            regexp_to_like(rhs_node)
+          else
+            return nil
+          end
+
+        lhs = Parser.translate_where(node.receiver, schema)
+        AST::Like.new(lhs, AST::Literal.new(pattern))
+      end
+
+      def self.handles?(node)
+        node.is_a?(AST::Like)
+      end
+
+      def self.render(node, params)
+        params << node.right.value
+        "#{node.left.name} LIKE ?"
+      end
+
+      # ----- Regexp -> LIKE translation -----
+
+      UNSUPPORTED = {
+        '(' => 'groups'.freeze,
+        ')' => 'groups'.freeze,
+        '|' => 'alternation'.freeze,
+        '+' => '+ quantifier'.freeze,
+        '?' => '? quantifier'.freeze,
+        '{' => '{n,m} quantifier'.freeze,
+        '[' => 'character class'.freeze
+      }.freeze
+
+      def self.regexp_to_like(regexp_node)
+        # `.content` is the raw source between the slashes; `.unescaped`
+        # would already process regex-level escapes (\n -> newline), which
+        # we don't want — we're translating the source, not matching it.
+        source = regexp_node.content
+        out = String.new
+        i = 0
+        len = source.length
+
+        leading_anchor = false
+        trailing_anchor = false
+
+        if len > 0 && source[0] == '^'
+          leading_anchor = true
+          i += 1
+        end
+        if len - i > 0 && source[len - 1] == '$'
+          trailing_anchor = true
+          len -= 1
+        end
+
+        while i < len
+          c = source[i]
+          if c == '\\' && i + 1 < len
+            nxt = source[i + 1]
+            out << escape_like(nxt)
+            i += 2
+          elsif c == '.'
+            # peek for .*
+            if i + 1 < len && source[i + 1] == '*'
+              out << '%'
+              i += 2
+            else
+              out << '_'
+              i += 1
+            end
+          elsif UNSUPPORTED.key?(c)
+            raise ArgumentError,
+                  "Regexp feature #{UNSUPPORTED[c].inspect} (#{c.inspect}) " \
+                  "is not supported by LIKE; rewrite without it"
+          else
+            out << escape_like(c)
+            i += 1
+          end
+        end
+
+        # ^X -> LIKE 'X%'   (starts with)
+        # X$ -> LIKE '%X'   (ends with)
+        # ^X$ -> LIKE 'X'   (exact)
+        # X -> LIKE '%X%'   (anywhere)
+        if leading_anchor && trailing_anchor
+          out
+        elsif leading_anchor
+          "#{out}%"
+        elsif trailing_anchor
+          "%#{out}"
+        else
+          "%#{out}%"
+        end
+      end
+
+      LIKE_WILDCARDS = { '%' => '\%'.freeze, '_' => '\_'.freeze, '\\' => '\\\\'.freeze }.freeze
+
+      def self.escape_like(ch)
+        LIKE_WILDCARDS.fetch(ch, ch)
+      end
+    end
+  end
+end
+
+Diamond::Parser::WhereOperators.register(Diamond::Operators::Like)
+Diamond::Compiler::Operators.register(Diamond::Operators::Like)

data/lib/diamond/parser/proxy.rb

@@ -0,0 +1,469 @@
+module Diamond
+  module Parser
+    # Runtime fallback for blocks with no source file on disk: (irb),
+    # (eval), `ruby -e`, pry. The Prism path re-parses the block's
+    # file, which doesn't exist here — so instead we execute the block
+    # against small recorders that build the same AST shapes the
+    # translators produce.
+    #
+    # THE REPL RULE: `&&` and `||` short-circuit inside Ruby itself and
+    # can never be intercepted, so console blocks must use `&` / `|`
+    # (or the hash/array where forms, which need no parsing at all).
+    # File-backed blocks keep full `&&` / `||` support via Prism.
+    #
+    # Deliberate divergences from the Prism path (console-only):
+    # - multi-statement where/derive/update blocks: only the last value
+    #   is visible (Prism validates statement counts);
+    # - custom WhereOperators/DeriveOperators hooks don't fire (they
+    #   match on Prism nodes);
+    # - reversed comparisons (`5 > age`) raise ArgumentError from Ruby
+    #   (placeholders define no coercion protocol);
+    # - string-method calls (`"x".upcase`) execute instead of being
+    #   silently dropped to the literal.
+    module Proxy
+      module_function
+
+      # File truthiness is not enough: (irb)/(eval)/-e are truthy
+      # pseudo-paths with no file behind them.
+      def file_backed?(block)
+        file, _line = block.source_location
+        !file.nil? && File.exist?(file)
+      end
+
+      # instance_exec passes the recorder as the block arg when it
+      # takes one (`|t|`), and nothing when it takes none — except
+      # strict lambdas, which check arity either way.
+      def exec_block(target, block)
+        if block.lambda? && block.arity == 0
+          target.instance_exec(&block)
+        else
+          target.instance_exec(target, &block)
+        end
+      end
+
+      def parse_where(block, schema, scope = nil)
+        proxy = SchemaProxy.new(schema, scope, allow_tables: true)
+        unwrap_where(exec_block(proxy, block))
+      end
+
+      def parse_derive(block, schema)
+        proxy = SchemaProxy.new(schema, nil, allow_tables: false)
+        [unwrap_derive(exec_block(proxy, block), schema)]
+      end
+
+      def parse_ddl(block)
+        rec = DdlRecorder.new
+        exec_block(rec, block)
+        rec.statements
+      end
+
+      def parse_update(block, schema)
+        rec = UpdateRecorder.new(schema)
+        result = exec_block(rec, block)
+        return rec.pairs unless rec.pairs.empty?
+        if result.is_a?(::Hash)
+          result.each_key do |key|
+            unless key.is_a?(::Symbol)
+              raise BlockMismatch, "Invalid update statement: keys must be Symbols, got #{key.inspect}"
+            end
+            Parser.validate_column!(key, schema)
+          end
+          return result
+        end
+        raise BlockMismatch, "update blocks use the smalltalk form (`age 17`)"
+      end
+
+      # Single coercion point for where positions: placeholders become
+      # their AST, Ruby values become literals. Symbols bind as strings
+      # (`kind == :text`), mirroring translate_where. Arrays and
+      # anything else are BlockMismatch, mirroring the Prism path's
+      # unsupported-node errors.
+      def unwrap_where(value)
+        case value
+        when Lazy then value.materialize
+        when AST::Node then value
+        when ::Symbol then AST::Literal.new(value.to_s)
+        when ::Integer, ::Float, ::String, ::TrueClass, ::FalseClass, ::NilClass
+          AST::Literal.new(value)
+        else
+          raise BlockMismatch, "Unsupported value in where block: #{value.inspect}"
+        end
+      end
+
+      # Derive binds symbols as COLUMNS (translate_derive validates
+      # SymbolNodes against the schema) — unlike where, which binds
+      # them as string literals.
+      def unwrap_derive(value, schema)
+        case value
+        when Lazy then value.materialize
+        when AST::Node then value
+        when ::Symbol
+          Parser.validate_column!(value, schema)
+          AST::Column.new(value)
+        when ::Integer, ::Float, ::String, ::TrueClass, ::FalseClass, ::NilClass
+          AST::Literal.new(value)
+        else
+          raise BlockMismatch, "Unsupported value in derive block: #{value.inspect}"
+        end
+      end
+
+      # Catches barewords (`age`), function calls (`count(id)`), and
+      # table refs (`tags` in scope). BasicObject so column names never
+      # collide with Kernel/Object methods — which also means every
+      # host call needs an explicit receiver (::Kernel.raise, Parser.*,
+      # ::Diamond.*).
+      class SchemaProxy < ::BasicObject
+        # allow_tables is false for derive: the file-backed derive
+        # translator has no scope concept and rejects qualified refs,
+        # so the console must too — otherwise code proven in a console
+        # would break the moment it moves into a file.
+        def initialize(schema, scope, allow_tables: true)
+          @schema = schema
+          @scope = scope
+          @allow_tables = allow_tables
+        end
+
+        def method_missing(name, *args, **kwargs, &blk)
+          unless args.empty? && kwargs.empty? && blk.nil?
+            return function_call(name, args)
+          end
+          if @allow_tables && table_ref?(name)
+            in_scope = @scope && @scope.key?(name) ? true : false
+            return TableRef.new(name, @schema, in_scope ? @scope[name] : nil, in_scope)
+          end
+          ::Diamond::Parser::Proxy::ColumnRef.new(name, @schema)
+        end
+
+        private
+
+        # A bareword is a table ref when it isn't a base column and is
+        # either joined (scope) or known to the engine (join hint).
+        # Mirrors try_qualified + join_first_hint gating.
+        def table_ref?(name)
+          return false if @schema[:columns].include?(name)
+          return true if @scope && @scope.key?(name)
+          engine_knows?(name)
+        end
+
+        # The engine probe needs a woken engine. Without one (unit
+        # tests, pre-wake consoles) treat the name as unknown: its
+        # later use raises UnknownColumnError via to_ast, which is
+        # more actionable than a boot error. With a woken engine this
+        # matches the Prism path exactly.
+        def engine_knows?(name)
+          ::Diamond.engine.schema_cache.key?(name)
+        rescue ::StandardError
+          false
+        end
+
+        # Bare function call: `count(id)`, `sum(age)`. Stays lazy so
+        # prefix operators (`!count(id)`) nest instead of collapsing;
+        # args validate as columns at materialize time.
+        def function_call(name, args)
+          ::Diamond::Parser::Proxy::Op.new(:fn, [name, args])
+        end
+      end
+
+      # Lazy condition tree. Operators return Lazy nodes instead of
+      # real AST so that prefix operators keep working: Ruby evaluates
+      # inside-out, so by the time `!` runs in `!(age > 10)` its
+      # operand is already built — if `>` returned a real AST node,
+      # `!` would hit BasicObject#! and collapse to `false`. With
+      # everything lazy, `!` nests properly and a single materialize
+      # pass at unwrap time builds the final tree. (This is also what
+      # makes chained comparisons work.)
+      #
+      # Standalone placeholders, deliberately NOT AST nodes, so the
+      # AST layer and its existing callers are untouched.
+      class Lazy
+        def >(other)
+          Op.new(:>, [self, other])
+        end
+
+        def <(other)
+          Op.new(:<, [self, other])
+        end
+
+        def >=(other)
+          Op.new(:>=, [self, other])
+        end
+
+        def <=(other)
+          Op.new(:<=, [self, other])
+        end
+
+        def ==(other)
+          Op.new(:==, [self, other])
+        end
+
+        # Ruby defines != as !(==); with our truthy == results that
+        # would nest Not(Equality) instead of NotEqual — so != stays
+        # explicit.
+        def !=(other)
+          Op.new(:!=, [self, other])
+        end
+
+        def !
+          Op.new(:not, [self])
+        end
+
+        def &(other)
+          Op.new(:and, [self, other])
+        end
+
+        def |(other)
+          Op.new(:or, [self, other])
+        end
+
+        # `in` via define_method: `def in` risks the pattern-matching
+        # keyword, while an explicit-receiver call (`x.in(1, 2)`) and a
+        # symbol-defined method are both unambiguous.
+        define_method(:in) do |*vals|
+          Op.new(:in, [self, vals])
+        end
+
+        def between?(low, high)
+          Op.new(:between, [self, low, high])
+        end
+
+        # Derive-only (`rank.over(partition_by: ...)`).
+        def over(partition_by: [], order: [])
+          Op.new(:over, [self, partition_by, order])
+        end
+
+        def materialize
+          raise NotImplementedError, "#{self.class} must implement materialize"
+        end
+      end
+
+      # A bareword (or qualified `table.col`). Validation is lazy in
+      # materialize: `rank.over(...)` must not validate `rank` as a
+      # column, mirroring translate_derive which never visits the
+      # over-receiver.
+      class ColumnRef < Lazy
+        attr_reader :name, :table
+
+        def initialize(name, schema, table: nil)
+          @name = name
+          @schema = schema
+          @table = table
+        end
+
+        def materialize
+          Parser.validate_column!(@name, @schema)
+          AST::Column.new(@name, table: @table)
+        end
+
+        # Console safety net: typos (`age.grate_than(10)`) raise a DSL
+        # error instead of NoMethodError. Safe to add — the file path
+        # never instantiates placeholders, and every DSL-called method
+        # (operators, in, between?, over) is defined above.
+        def method_missing(name, *_args, **_kwargs, &_blk)
+          raise BlockMismatch, "Unknown column method: #{@name}.#{name}"
+        end
+      end
+
+      # One deferred operation. Materialization mirrors the Prism
+      # translators exactly: nil comparisons become IS [NOT] NULL,
+      # symbols bind as strings, barewords validate as columns.
+      class Op < Lazy
+        def initialize(op, children)
+          @op = op
+          @children = children
+        end
+
+        def materialize
+          case @op
+          when :>
+            AST::GreaterThan.new(mat0, coerce(@children[1]))
+          when :<
+            AST::LessThan.new(mat0, coerce(@children[1]))
+          when :>=
+            AST::GreaterEqual.new(mat0, coerce(@children[1]))
+          when :<=
+            AST::LessEqual.new(mat0, coerce(@children[1]))
+          when :==
+            return AST::IsNull.new(mat0) if @children[1].nil?
+            AST::Equality.new(mat0, coerce(@children[1]))
+          when :!=
+            return AST::IsNotNull.new(mat0) if @children[1].nil?
+            AST::NotEqual.new(mat0, coerce(@children[1]))
+          when :not
+            AST::Not.new(mat(@children[0]))
+          when :and
+            AST::And.new(mat(@children[0]), mat(@children[1]))
+          when :or
+            AST::Or.new(mat(@children[0]), mat(@children[1]))
+          when :in
+            AST::In.new(mat0, Array(@children[1]).flatten(1).map { |v| coerce(v) })
+          when :between
+            AST::Between.new(mat0, coerce(@children[1]), coerce(@children[2]))
+          when :fn
+            AST::Function.new(@children[0], @children[1].map { |a| coerce(a) })
+          when :over
+            materialize_over
+          end
+        end
+
+        private
+
+        # Operands arrive as raw Ruby values, ColumnRefs, or nested
+        # Ops — unwrap_where funnels every shape through materialize.
+        def mat(node)
+          Proxy.unwrap_where(node)
+        end
+
+        def mat0
+          mat(@children[0])
+        end
+
+        alias coerce mat
+
+        # The over-receiver must be a bareword in WINDOW_FUNCS —
+        # mirroring translate_derive, which rejects anything else.
+        def materialize_over
+          recv = @children[0]
+          unless recv.is_a?(ColumnRef)
+            raise BlockMismatch, "Window function receiver must be a bareword call: #{recv.inspect}"
+          end
+          unless Parser::WINDOW_FUNCS.include?(recv.name)
+            raise BlockMismatch, "Not a window function: #{recv.name.inspect}"
+          end
+          AST::WindowFunction.new(
+            recv.name, [],
+            partition_by: Array(@children[1]).map(&:to_sym),
+            order_by: Array(@children[2]).map(&:to_sym),
+          )
+        end
+      end
+
+      # `tags` in `tags.tag`: validated against the joined table's
+      # schema, or raises the join-first hint when the table is known
+      # to the engine but not joined. Mirrors try_qualified.
+      #
+      # Subclasses ColumnRef so a bare table in any other position
+      # (comparison, function arg) validates as a bareword against the
+      # base schema — exactly what the Prism path does with it.
+      class TableRef < ColumnRef
+        def initialize(table, base_schema, table_schema, in_scope)
+          super(table, base_schema)
+          @table_schema = table_schema
+          @in_scope = in_scope
+        end
+
+        def method_missing(col, *args, **kwargs, &blk)
+          unless args.empty? && kwargs.empty? && blk.nil?
+            raise BlockMismatch, "Unsupported call: #{@name}.#{col}"
+          end
+          unless @in_scope
+            ::Kernel.raise(::ArgumentError,
+              "filtering on '#{@name}.#{col}' needs `.join(:#{@name})` first " \
+              "(joins must come before the where that filters on them)")
+          end
+          Parser.validate_column!(col, @table_schema)
+          Proxy::ColumnRef.new(col, @table_schema, table: @name)
+        end
+      end
+
+      # Executes DDL blocks (`do |t| t.attribute ... end`, and the bare
+      # `attribute ...` form via instance_exec self) building the same
+      # AST nodes translate_ddl_stmt builds.
+      class DdlRecorder
+        attr_reader :statements
+
+        def initialize
+          @statements = []
+        end
+
+        def attribute(name, type, **opts)
+          check_name!(name, "attribute")
+          check_type!(type)
+          @statements << AST::ColumnDefinition.new(name, type, opts)
+        end
+
+        def add_column(name, type, **opts)
+          check_name!(name, "add_column")
+          check_type!(type)
+          @statements << AST::ColumnDefinition.new(name, type, opts)
+        end
+
+        def primary_key(name)
+          check_name!(name, "primary_key")
+          @statements << AST::ColumnDefinition.new(name, Integer, primary_key: true, nullable: false)
+        end
+
+        def foreign_key(local, ref_table, ref_col = :id, on_delete: nil, on_update: nil)
+          check_name!(local, "foreign_key")
+          check_name!(ref_table, "foreign_key")
+          check_name!(ref_col, "foreign_key")
+          on_delete = check_fk_action!(:on_delete, on_delete)
+          on_update = check_fk_action!(:on_update, on_update)
+          @statements << AST::ForeignKey.new(local, ref_table, ref_col,
+                                             on_delete: on_delete, on_update: on_update)
+        end
+
+        def index(*cols, name: nil, unique: false)
+          raise ArgumentError, "index requires `name:` kwarg" if name.nil?
+          raise ArgumentError, "index requires at least one column" if cols.empty?
+          cols.each { |c| check_name!(c, "index") }
+          @statements << AST::IndexDefinition.new(name, cols, unique: !!unique)
+        end
+
+        # Mirror translate_ddl_stmt's unknown-method rejection (there a
+        # BlockMismatch, not NoMethodError).
+        def method_missing(name, *_args, **_kwargs, &_blk)
+          raise BlockMismatch, "Unknown DDL method: #{name}"
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          Parser::DDL_METHODS.include?(name) || super
+        end
+
+        private
+
+        def check_name!(value, what)
+          return if value.is_a?(::Symbol)
+          raise ArgumentError, "#{what} name must be a Symbol, got #{value.inspect}"
+        end
+
+        def check_type!(type)
+          return if type.is_a?(::Module)
+          raise ArgumentError, "Type must be a constant (e.g., Integer, String)"
+        end
+
+        def check_fk_action!(key, value)
+          return nil if value.nil?
+          sym = value.to_sym
+          unless Parser::DDL_FK_ACTIONS.include?(sym)
+            raise ArgumentError, "unknown #{key} action: #{value.inspect}; must be one of #{Parser::DDL_FK_ACTIONS.inspect}"
+          end
+          sym
+        end
+      end
+
+      # Executes smalltalk update blocks (`age 17`). One bareword call
+      # with one positional arg per statement, mirroring the Prism
+      # path's shape check.
+      class UpdateRecorder
+        attr_reader :pairs
+
+        def initialize(schema)
+          @schema = schema
+          @pairs = {}
+        end
+
+        def method_missing(name, *args, **kwargs, &blk)
+          unless args.size == 1 && kwargs.empty? && blk.nil?
+            raise BlockMismatch, "Invalid update statement: #{name}"
+          end
+          Parser.validate_column!(name, @schema)
+          @pairs[name] = args.first
+        end
+
+        def respond_to_missing?(_name, _include_private = false)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/diamond/parser/registry.rb

@@ -0,0 +1,74 @@
+module Diamond
+  module Parser
+    # Registry consulted at the front of translate_where. External operators
+    # run first, sorted by descending priority. First non-nil result wins.
+    # Built-ins are implicit priority 0 (they fall through).
+    #
+    # Per-Ractor: each Ractor owns its own handler list, stored on the
+    # Ractor's own local storage. The module holds only the frozen list of
+    # built-ins (which is shareable).
+    module WhereOperators
+      STORAGE_KEY = Diamond::RACTOR_KEYS[:where_ops]
+
+      # method, not a constant: this file loads before the Like operator
+      # is defined, so it must resolve lazily. called once per Ractor
+      # (handlers memoizes), so the per-call allocation is irrelevant.
+      def self.builtins
+        [Diamond::Operators::Like].freeze
+      end
+
+      def self.handlers
+        Ractor.current[STORAGE_KEY] ||= builtins.dup
+      end
+
+      def self.register(operator)
+        list = handlers
+        list << operator unless list.include?(operator)
+        nil
+      end
+
+      def self.clear!
+        Ractor.current[STORAGE_KEY] = builtins.dup
+      end
+
+      def self.call(node, schema)
+        handlers.sort_by { |h| -h.priority }.each do |h|
+          result = h.parse_where(node, schema)
+          return result if result
+        end
+        nil
+      end
+    end
+
+    # Registry consulted at the front of translate_derive.
+    module DeriveOperators
+      STORAGE_KEY = Diamond::RACTOR_KEYS[:derive_ops]
+
+      def self.builtins
+        [].freeze  # no built-in derive operators yet
+      end
+
+      def self.handlers
+        Ractor.current[STORAGE_KEY] ||= builtins.dup
+      end
+
+      def self.register(operator)
+        list = handlers
+        list << operator unless list.include?(operator)
+        nil
+      end
+
+      def self.clear!
+        Ractor.current[STORAGE_KEY] = builtins.dup
+      end
+
+      def self.call(node, schema)
+        handlers.sort_by { |h| -h.priority }.each do |h|
+          result = h.parse_derive(node, schema)
+          return result if result
+        end
+        nil
+      end
+    end
+  end
+end