arfi 0.5.0 → 1.0.0

data/lib/arfi/commands/functions_rendering.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Arfi
+  module Commands
+    # Table rendering helpers for {Arfi::Commands::Functions}.
+    module FunctionsRendering
+      private
+
+      # Render the resolved function list in the selected format (paths, json, or table).
+      #
+      # @private
+      # @param [Array<Hash<Symbol, Object>>] rows Resolved function rows
+      # @return [void]
+      def render_list(rows)
+        case options[:format].to_s
+        when 'paths'
+          rows.each { puts rel(_1[:path]) }
+        when 'json'
+          puts JSON.pretty_generate(rows.map { |r| r.merge(path: rel(r[:path])) })
+        else
+          print_table(rows)
+        end
+      end
+
+      # Print the function list as a formatted ASCII table.
+      #
+      # @private
+      # @param [Array<Hash<Symbol, Object>>] rows Resolved function rows
+      # @return [void]
+      def print_table(rows)
+        cols = table_columns
+        table = stringify_rows(rows)
+        widths = calculate_widths(cols, table)
+        puts cols.map { |c| c.ljust(widths[c]) }.join('  ')
+        puts cols.map { |c| '-' * widths[c] }.join('  ')
+        render_table_rows(table, cols, widths)
+      end
+
+      # Determine which columns to display based on the --all flag.
+      #
+      # @private
+      # @return [Array<String>] List of column names
+      def table_columns
+        if options[:all]
+          %w[chosen schema function source origin priority path shadowed_by]
+        else
+          %w[schema function source origin priority path shadowed]
+        end
+      end
+
+      # Convert all row values to strings for display, handling special columns.
+      #
+      # @private
+      # @param [Array<Hash<Symbol, Object>>] rows Resolved function rows
+      # @return [Array<Hash<Symbol, Object>>] Rows with string values
+      def stringify_rows(rows)
+        rows.map do |r|
+          r = r.dup
+          r[:path] = rel(r[:path])
+          r[:chosen] = r[:chosen] ? 'yes' : 'no' if r.key?(:chosen)
+          r[:shadowed] = (r[:shadowed] || []).join(', ') if r.key?(:shadowed)
+          r
+        end
+      end
+
+      # Calculate the maximum display width for each column.
+      #
+      # @private
+      # @param [Array<String>] cols Column names
+      # @param [Array<Hash<Symbol, Object>>] table Stringified table rows
+      # @return [Hash<String, Integer>] Column widths keyed by column name
+      def calculate_widths(cols, table)
+        widths = {} # steep:ignore
+        cols.each do |c|
+          widths[c] = ([c.length] + table.map { |r| r[c.to_sym].to_s.length }).max
+        end
+        widths
+      end
+
+      # Render each table row with proper column alignment.
+      #
+      # @private
+      # @param [Array<Hash<Symbol, Object>>] table Stringified table rows
+      # @param [Array<String>] cols Column names
+      # @param [Hash<String, Integer>] widths Calculated column widths
+      # @return [void]
+      def render_table_rows(table, cols, widths)
+        table.each do |r|
+          puts cols.map { |c| r[c.to_sym].to_s.ljust(widths[c]) }.join('  ')
+        end
+      end
+
+      # Resolve a group of same-key candidates to the chosen one with shadowed info.
+      #
+      # @private
+      # @param [Array<Arfi::Commands::candidate>] arr Candidates for one function key
+      # @return [Array<Hash<Symbol, Object>>] Resolved row(s) for display
+      def resolve_key_group(arr)
+        chosen = arr.max_by { |c| c[:priority] }
+        return [] unless chosen
+
+        if options[:all]
+          all_mode_rows(arr, chosen)
+        else
+          default_mode_row(chosen, arr)
+        end
+      end
+
+      # Build display rows for --all mode (shows all candidates including overridden ones).
+      #
+      # @private
+      # @param [Array<Arfi::Commands::candidate>] arr All candidates for one function key
+      # @param [Arfi::Commands::candidate] chosen The selected (highest-priority) candidate
+      # @return [Array<Hash<Symbol, Object>>] Display rows
+      def all_mode_rows(arr, chosen)
+        chosen_path = chosen[:path]
+        arr.sort_by { |c| [-c[:priority], c[:schema], c[:function]] }.map do |c|
+          c.merge(
+            chosen: (c == chosen),
+            shadowed_by: (c == chosen ? nil : rel(chosen_path))
+          )
+        end
+      end
+
+      # Build a single display row for default mode (only the chosen candidate).
+      #
+      # @private
+      # @param [Arfi::Commands::candidate] chosen The selected (highest-priority) candidate
+      # @param [Array<Arfi::Commands::candidate>] arr All candidates for one function key
+      # @return [Array<Hash<Symbol, Object>>] Single display row
+      def default_mode_row(chosen, arr)
+        shadowed = (arr - [chosen])
+        [chosen.merge(chosen: true, shadowed: shadowed.map { rel(_1[:path]) })]
+      end
+    end
+  end
+end

data/lib/arfi/commands/init.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'fileutils'
+require 'rails'
+
+module Arfi
+  module Commands
+    # Initializes ARFI directory structure inside a Rails project.
+    #
+    # Creates/ensures:
+    # - db/functions/public
+    # - db/functions/<adapter>/public (when adapter provided)
+    #
+    # @api public
+    class Init < Thor
+      ADAPTERS = %i[postgresql mysql].freeze
+      ROOT_DIR = 'db/functions'
+      DEFAULT_SCHEMA = 'public'
+
+      default_task :create
+
+      # UX aliases
+      map %w[setup] => :create
+
+      desc 'create', 'Initialize project by creating db/functions structure (explicit public schema dirs)'
+      option :adapter, type: :string,
+                       desc: "Specify database adapter. Available adapters: #{ADAPTERS.join(', ')}",
+                       banner: 'adapter'
+
+      # Run the full init flow: validate schema, create base dirs, and optionally create adapter dirs.
+      #
+      # @return [void]
+      def create
+        validate_schema_format!
+        create_base_dirs
+        create_adapter_dirs if options[:adapter] # steep:ignore NoMethod
+      end
+
+      private
+
+      # Validate that the Rails schema format is set to :ruby.
+      #
+      # @private
+      # @raise [Arfi::Errors::InvalidSchemaFormat] If schema format is not :ruby
+      # @return [void]
+      def validate_schema_format!
+        fmt =
+          if defined?(Rails) && Rails.application
+            Rails.application.config.active_record.schema_format
+          elsif defined?(ActiveRecord::Base) && ActiveRecord::Base.respond_to?(:schema_format)
+            ActiveRecord::Base.schema_format
+          end
+
+        raise Arfi::Errors::InvalidSchemaFormat unless fmt == :ruby
+      end
+
+      # Create the base db/functions and db/functions/public directories.
+      #
+      # @private
+      # @return [void]
+      def create_base_dirs
+        root = Rails.root.join(ROOT_DIR)
+        FileUtils.mkdir_p(root)
+        puts "Ensured: #{root}"
+        FileUtils.mkdir_p(root.join(DEFAULT_SCHEMA))
+        puts "Ensured: #{root.join(DEFAULT_SCHEMA)}"
+      end
+
+      # Create the adapter-specific function directories (e.g. db/functions/postgresql/public).
+      #
+      # @private
+      # @raise [Arfi::Errors::AdapterNotSupported] If adapter is not in the supported list
+      # @return [void]
+      def create_adapter_dirs
+        adapter = options[:adapter].to_s # steep:ignore NoMethod
+        raise Arfi::Errors::AdapterNotSupported unless ADAPTERS.include?(adapter.to_sym)
+
+        root = Rails.root.join(ROOT_DIR)
+        adapter_root = root.join(adapter)
+        FileUtils.mkdir_p(adapter_root)
+        puts "Ensured: #{adapter_root}"
+        FileUtils.mkdir_p(adapter_root.join(DEFAULT_SCHEMA))
+        puts "Ensured: #{adapter_root.join(DEFAULT_SCHEMA)}"
+      end
+    end
+  end
+end

data/lib/arfi/commands/project.rb

@@ -1,59 +1,13 @@
 # frozen_string_literal: true
 
-require 'thor'
-require 'fileutils'
-require 'rails'
+require_relative 'init'
 
 module Arfi
   module Commands
     # +Arfi::Commands::Project+ class is used to create `db/functions` directory.
-    class Project < Thor
-      ADAPTERS = %i[postgresql mysql].freeze
-
-      # steep:ignore:start
-      desc 'create', 'Initialize project by creating db/functions directory'
-      option :adapter, type: :string,
-                       desc: 'Specify database adapter, used for projects with multiple database architecture. ' \
-                             "Available adapters: #{ADAPTERS.join(', ')}",
-                       banner: 'adapter'
-      # steep:ignore:end
-
-      # +Arfi::Commands::Project#create+                 -> void
-      #
-      # This command is used to create `db/functions` directory.
-      #
-      # @example
-      #   bundle exec arfi project create
-      # @return [void]
-      # @raise [Arfi::Errors::InvalidSchemaFormat] if ActiveRecord.schema_format is not :ruby.
-      def create
-        raise Arfi::Errors::InvalidSchemaFormat unless ActiveRecord.schema_format == :ruby # steep:ignore NoMethod
-        return puts "Directory #{functions_dir} already exists" if Dir.exist?(functions_dir)
-
-        FileUtils.mkdir_p(functions_dir)
-        puts "Created: #{functions_dir}"
-      end
-
-      private
-
-      # +Arfi::Commands::Project#functions_dir+          -> Pathname
-      #
-      # Helper method to get path to `db/functions` directory.
-      #
-      # @!visibility private
-      # @private
-      # @return [Pathname] Path to `db/functions` directory
-      def functions_dir
-        # steep:ignore:start
-        if options[:adapter]
-          raise Arfi::Errors::AdapterNotSupported unless ADAPTERS.include?(options[:adapter].to_sym)
-
-          Rails.root.join("db/functions/#{options[:adapter]}")
-          # steep:ignore:end
-        else
-          Rails.root.join('db/functions')
-        end
-      end
-    end
+    #
+    # Backward-compatible constant for code that references Arfi::Commands::Project.
+    # @deprecated
+    Project = Init
   end
 end

data/lib/arfi/errors.rb

@@ -2,8 +2,12 @@
 
 module Arfi
   module Errors
-    # This error is raised when there is no `db/functions` directory
+    # Raised when there is no `db/functions` directory in the Rails project.
     class NoFunctionsDir < StandardError
+      # Initialize a new NoFunctionsDir error with an optional custom message.
+      #
+      # @param [String] message Error message
+      # @return [void]
       def initialize(message =
                        'There is no such directory: db/functions. Did you run `bundle exec arfi project:create`?')
         @message = message
@@ -11,16 +15,24 @@ module Arfi
       end
     end
 
-    # This error is raised when Rails project schema format is not +schema.rb+
+    # Raised when Rails schema format is not ruby (`schema.rb`).
     class InvalidSchemaFormat < StandardError
+      # Initialize a new InvalidSchemaFormat error with an optional custom message.
+      #
+      # @param [String] message Error message
+      # @return [void]
       def initialize(message = 'Invalid schema format. ARFI supports only ruby format schemas.')
         @message = message
         super
       end
     end
 
-    # This error is raised when database adapter is not supported (for e.g., SQLite3).
+    # Raised when the configured/selected adapter is not supported by ARFI.
     class AdapterNotSupported < StandardError
+      # Initialize a new AdapterNotSupported error with an optional custom message.
+      #
+      # @param [String] message Error message
+      # @return [void]
       def initialize(message = 'Adapter not supported')
         @message = message
         super

data/lib/arfi/extensions/active_record/base.rb

@@ -4,33 +4,43 @@ require 'active_record'
 
 module ActiveRecord
   class Base # :nodoc:
-    # +ActiveRecord::Base.function_exists?+               -> bool
+    # Check if a SQL function exists in the database, dispatching to the correct adapter method.
     #
-    # This method checks if a custom SQL function exists in the database.
-    #
-    # @example
-    #   ActiveRecord::Base.function_exists?('my_function') #=> true
-    #   ActiveRecord::Base.function_exists?('my_function123') #=> false
-    # @param [String] function_name The name of the function to check.
-    # @return [Boolean] Returns true if the function exists, false otherwise.
-    def self.function_exists?(function_name) # rubocop:disable Metrics/MethodLength
-      case connection
-      when ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
-        connection.execute("SELECT * FROM pg_proc WHERE proname = '#{function_name}'").any?
-      when ActiveRecord::ConnectionAdapters::Mysql2Adapter
-        sql = <<~SQL
-          SELECT 1
-          FROM information_schema.ROUTINES
-          WHERE ROUTINE_TYPE = 'FUNCTION'
-            AND ROUTINE_SCHEMA = '#{connection.current_database}'
-            AND ROUTINE_NAME = '#{function_name}'
-          LIMIT 1;
-        SQL
-
-        !!connection.execute(sql).first
+    # @param [String] function_name Function name to check
+    # @raise [ActiveRecord::AdapterNotFound] If adapter is not supported
+    # @return [Boolean] Whether the function exists
+    def self.function_exists?(function_name)
+      case connection.class.name
+      when 'ActiveRecord::ConnectionAdapters::PostgreSQLAdapter'
+        pg_function_exists?(function_name)
+      when 'ActiveRecord::ConnectionAdapters::Mysql2Adapter', 'ActiveRecord::ConnectionAdapters::TrilogyAdapter'
+        mysql_function_exists?(function_name)
       else
         raise ActiveRecord::AdapterNotFound, "adapter #{connection.class.name} is not supported"
       end
     end
+
+    # Check if a function exists in PostgreSQL via pg_proc catalog table.
+    #
+    # @param [String] function_name Function name to check
+    # @return [Boolean] Whether the function exists
+    def self.pg_function_exists?(function_name)
+      sql = "SELECT 1 FROM pg_proc WHERE proname = #{connection.quote(function_name)} LIMIT 1"
+      !connection.select_value(sql).nil?
+    end
+
+    # Check if a function exists in MySQL/MariaDB via information_schema.ROUTINES.
+    #
+    # @param [String] function_name Function name to check
+    # @return [Boolean] Whether the function exists
+    def self.mysql_function_exists?(function_name)
+      !connection.select_value(<<~SQL).nil?
+        SELECT 1 FROM information_schema.ROUTINES
+        WHERE ROUTINE_TYPE = 'FUNCTION'
+          AND ROUTINE_SCHEMA = #{connection.quote(connection.current_database)}
+          AND ROUTINE_NAME = #{connection.quote(function_name)}
+        LIMIT 1;
+      SQL
+    end
   end
 end

data/lib/arfi/extensions/active_record/connection_adapters/postgresql/database_statements.rb

@@ -1,32 +1,167 @@
 # frozen_string_literal: true
 
-require 'active_record/connection_adapters/postgresql/database_statements'
-
-module ActiveRecord
-  module ConnectionAdapters
-    module PostgreSQL
-      module DatabaseStatements
-        # This patch is used for db:prepare task.
-        def raw_execute(sql, name, async: false, allow_retry: false, materialize_transactions: true)
-          log(sql, name, async: async) do |notification_payload|
-            with_raw_connection(allow_retry: allow_retry, materialize_transactions: materialize_transactions) do |conn|
-              result = conn.async_exec(sql)
-              verified!
-              handle_warnings(result)
-              notification_payload[:row_count] = result.count
-              result
-            rescue => e
-              if e.message.match?(/ERROR:\s{2}function (\S+\(\w+\)) does not exist/)
-                function_name = e.message.match(/ERROR:\s{2}function (\S+\(\w+\)) does not exist/)[1][/^[^(]*/]
-                if (function_file = Dir.glob(Rails.root.join('db', 'functions', "#{function_name}_v*.sql").to_s).first)
-                  conn.async_exec(File.read(function_file).chop)
-                  retry
-                end
-              end
-            end
+begin
+  require "active_record/connection_adapters/postgresql_adapter"
+rescue LoadError
+  # no postgres adapter; ok
+end
+
+require "arfi/sql_function_loader"
+
+module Arfi
+  module PostgreSQL
+    # ActiveRecord adapter patch for PostgreSQL.
+    #
+    # When a query fails with `PG::UndefinedFunction`, ARFI checks whether the missing function
+    # is managed by ARFI (file exists under db/functions). If yes, ARFI loads function SQL files
+    # via {Arfi::SqlFunctionLoader.load!} and retries the failed query once.
+    #
+    # @api public
+    module DatabaseStatementsPatch
+      ARFI_UNDEFINED_FUNCTION = /
+        function\s+([a-zA-Z0-9_."]+)\s*\(.*?\)\s+does\s+not\s+exist
+      /ix.freeze
+
+      THREAD_GUARD_KEY = :arfi_reloading_functions
+
+      # Execute a SQL query, reloading missing ARFI-managed functions and retrying on PG::UndefinedFunction.
+      #
+      # @param [Array<Object>] args Positional arguments forwarded to the original exec_query
+      # @param [Object] kwargs Keyword arguments forwarded to the original exec_query
+      # @raise [StandardError] If the error is not recoverable
+      # @return [Object] Query result
+      # @return [Object] if StandardError (retry successful)
+      def exec_query(*args, **kwargs)
+        super
+      rescue StandardError => e
+        raise unless arfi_try_reload_and_retry?(e)
+        retry
+      end
+
+      # Execute raw SQL, reloading missing ARFI-managed functions and retrying on PG::UndefinedFunction.
+      #
+      # @param [Array<Object>] args Positional arguments forwarded to the original execute
+      # @param [Object] kwargs Keyword arguments forwarded to the original execute
+      # @raise [StandardError] If the error is not recoverable
+      # @return [Object] Execution result
+      # @return [Object] if StandardError (retry successful)
+      def execute(*args, **kwargs)
+        super
+      rescue StandardError => e
+        raise unless arfi_try_reload_and_retry?(e)
+        retry
+      end
+
+      # Execute a raw SQL statement, reloading missing ARFI-managed functions and retrying on PG::UndefinedFunction.
+      #
+      # @param [Array<Object>] args Positional arguments forwarded to the original raw_execute
+      # @param [Object] kwargs Keyword arguments forwarded to the original raw_execute
+      # @raise [StandardError] If the error is not recoverable
+      # @return [Object] Execution result
+      # @return [Object] if StandardError (retry successful)
+      def raw_execute(*args, **kwargs)
+        super
+      rescue StandardError => e
+        raise unless arfi_try_reload_and_retry?(e)
+        retry
+      end
+
+      # Execute an internal query, reloading missing ARFI-managed functions and retrying on PG::UndefinedFunction.
+      #
+      # @param [Array<Object>] args Positional arguments forwarded to the original internal_exec_query
+      # @param [Object] kwargs Keyword arguments forwarded to the original internal_exec_query
+      # @raise [StandardError] If the error is not recoverable
+      # @return [Object] Query result
+      # @return [Object] if StandardError (retry successful)
+      def internal_exec_query(*args, **kwargs)
+        super
+      rescue StandardError => e
+        raise unless arfi_try_reload_and_retry?(e)
+        retry
+      end
+
+      private
+
+      # Check if the error is caused by a missing ARFI-managed function and attempt to reload it.
+      #
+      # Uses a thread guard to prevent recursive retries.
+      #
+      # @private
+      # @param [Object] e The raised exception (StandardError with possible PG::UndefinedFunction cause)
+      # @return [Boolean] Whether the error was handled (reload attempted)
+      def arfi_try_reload_and_retry?(e)
+        pg_error = e.cause || e
+        return false unless pg_error.class.name == "PG::UndefinedFunction"
+        return false if Thread.current[THREAD_GUARD_KEY]
+
+        schema, fn = arfi_extract_function_ident(pg_error.message)
+        return false unless arfi_has_function_file_for?(schema, fn)
+
+        Thread.current[THREAD_GUARD_KEY] = true
+        begin
+          Arfi::SqlFunctionLoader.load!(
+            task_name: "arfi:runtime",
+            connection: self,                # same connection
+            clear_active_connections: false, # runtime retry path
+            verbose: false
+          )
+        ensure
+          Thread.current[THREAD_GUARD_KEY] = false
+        end
+
+        true
+      end
+
+      # Extract the schema and function name from a PG::UndefinedFunction error message.
+      #
+      # @private
+      # @param [Object] message The error message string
+      # @return [Array<nil>, Object] Array of [schema, function_name] or [nil, nil] if not matched
+      def arfi_extract_function_ident(message)
+        m = message.to_s.match(ARFI_UNDEFINED_FUNCTION)
+        return [nil, nil] unless m
+
+        ident = m[1].to_s.delete('"')
+        parts = ident.split(".", 2)
+        parts.length == 2 ? [parts[0], parts[1]] : [nil, parts[0]]
+      end
+
+      # Check whether a function file exists under db/functions for the given schema and function name.
+      #
+      # @private
+      # @param [Object] schema Schema name (possibly nil)
+      # @param [Object] fn Function name
+      # @return [Boolean, Object] Whether a matching file exists on disk
+      def arfi_has_function_file_for?(schema, fn)
+        return false if fn.nil? || fn.empty?
+
+        root = Rails.root.join("db", "functions")
+        return false unless root.directory?
+
+        candidates = []
+        candidates << root.join("public", "#{fn}.sql")
+        candidates << root.join("#{fn}.sql") # legacy generic
+
+        pg_root = root.join("postgresql")
+        if pg_root.directory?
+          candidates << pg_root.join("public", "#{fn}.sql")
+          candidates << pg_root.join("#{fn}.sql") # legacy adapter
+
+          if schema && !schema.empty?
+            candidates << pg_root.join(schema, "#{fn}.sql")
+          else
+            candidates.concat Dir.glob(pg_root.join("*", "#{fn}.sql").to_s)
           end
         end
+
+        candidates.any? { |p| File.exist?(p) }
       end
     end
   end
 end
+
+if defined?(ActiveRecord::ConnectionAdapters::PostgreSQLAdapter)
+  ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.prepend(
+    Arfi::PostgreSQL::DatabaseStatementsPatch
+  )
+end