arfi 0.5.0 → 1.0.0

data/lib/arfi/commands/functions_candidates.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Arfi
+  module Commands
+    # Candidate discovery helpers for {Arfi::Commands::Functions}.
+    module FunctionsCandidates
+      private
+
+      # Collect all function candidates from generic, adapter, and (for PostgreSQL) schema directories.
+      #
+      # @private
+      # @param [Pathname] root Project root directory (Rails.root/db/functions)
+      # @param [String] adapter Database adapter name (postgresql, mysql, trilogy)
+      # @return [Array<Arfi::Commands::candidate>]
+      def collect_all_candidates(root, adapter)
+        candidates = generic_candidates(root)
+        adapter_root = root.join(adapter)
+        return candidates unless adapter_root.directory?
+
+        candidates.concat adapter_candidates(adapter_root, adapter)
+        candidates.concat collect_postgresql_schema_candidates(adapter_root, adapter) if adapter == 'postgresql'
+        candidates
+      end
+
+      # Group candidates by their schema/function key, sorted by priority within each group.
+      #
+      # @private
+      # @param [Array<Arfi::Commands::candidate>] candidates Flat list of candidates
+      # @return [Hash<String, Array<Arfi::Commands::candidate>>]
+      def group_candidates_by_key(candidates)
+        by_key = Hash.new { |h, k| h[k] = [] } # steep:ignore
+        candidates.each do |c|
+          by_key[c[:key]] << c
+        end
+        by_key.each_value { |arr| arr.sort_by! { |c| c[:priority] } }
+        by_key
+      end
+
+      # Build the final resolved rows by picking the highest-priority candidate per key.
+      #
+      # @private
+      # @param [Hash<String, Array<Arfi::Commands::candidate>>] by_key Candidates grouped by key
+      # @return [Array<Hash<Symbol, Object>>]
+      def build_resolved_rows(by_key)
+        by_key.keys.sort.flat_map do |key|
+          resolve_key_group(by_key[key])
+        end.compact
+      end
+
+      # Convert an absolute filesystem path to a project-relative path.
+      #
+      # @private
+      # @param [Pathname, String] path Absolute filesystem path
+      # @return [String] Relative path starting from Rails.root
+      def rel(path)
+        root = Rails.root.to_s
+        p = path.to_s
+        p.start_with?(root) ? p.sub(root + File::SEPARATOR, '') : p
+      end
+
+      # Collect generic function candidates from legacy root and explicit public/ directory.
+      #
+      # @private
+      # @param [Pathname] root Project root directory (Rails.root/db/functions)
+      # @return [Array<Arfi::Commands::candidate>]
+      def generic_candidates(root)
+        candidates = [] # steep:ignore
+        candidates.concat collect_candidates(glob: root.join('*.sql'), schema: DEFAULT_SCHEMA, source: 'generic',
+                                             origin: 'legacy', priority: 1)
+        candidates.concat collect_candidates(glob: root.join(DEFAULT_SCHEMA, '*.sql'), schema: DEFAULT_SCHEMA,
+                                             source: 'generic', origin: 'explicit', priority: 2)
+        candidates
+      end
+
+      # Collect function candidates from an adapter-specific directory (legacy + explicit public).
+      #
+      # @private
+      # @param [Pathname] adapter_root Adapter root directory (e.g. db/functions/postgresql)
+      # @param [String] adapter Database adapter name
+      # @return [Array<Arfi::Commands::candidate>]
+      def adapter_candidates(adapter_root, adapter)
+        candidates = [] # steep:ignore
+        candidates.concat collect_candidates(glob: adapter_root.join('*.sql'), schema: DEFAULT_SCHEMA,
+                                             source: adapter, origin: 'legacy', priority: 8)
+        candidates.concat collect_candidates(glob: adapter_root.join(DEFAULT_SCHEMA, '*.sql'),
+                                             schema: DEFAULT_SCHEMA, source: adapter, origin: 'explicit', priority: 9)
+        candidates
+      end
+
+      # Collect function candidates from PostgreSQL-specific schema subdirectories (except public).
+      #
+      # @private
+      # @param [Pathname] adapter_root PostgreSQL adapter root directory
+      # @param [String] adapter Database adapter name
+      # @return [Array<Arfi::Commands::candidate>]
+      def collect_postgresql_schema_candidates(adapter_root, adapter)
+        Dir.children(adapter_root).sort.each_with_object([]) do |child, acc|
+          next if child.start_with?('_')
+          next if child == DEFAULT_SCHEMA
+
+          dir = adapter_root.join(child)
+          next unless dir.directory?
+
+          acc.concat collect_candidates(glob: dir.join('*.sql'), schema: child, source: adapter,
+                                        origin: 'explicit', priority: 10)
+        end
+      end
+
+      # Collect SQL file candidates matching a glob pattern, skipping underscore-prefixed files.
+      #
+      # @private
+      # @param [Pathname] glob Glob pattern to match SQL files
+      # @param [String] schema Schema name to assign to all matched files
+      # @param [String] source Source type ('generic' or adapter name)
+      # @param [String] origin Origin type ('legacy' for root level, 'explicit' for public/ subdirectory)
+      # @param [Integer] priority Numeric priority for override resolution (higher = preferred)
+      # @return [Array<Arfi::Commands::candidate>]
+      def collect_candidates(glob:, schema:, source:, origin:, priority:)
+        Dir.glob(glob.to_s).filter_map do |path|
+          base = File.basename(path)
+          next if base.start_with?('_')
+
+          key = "#{schema}/#{base}"
+          function_name = File.basename(path, '.sql')
+          {
+            key: key, schema: schema, function: function_name,
+            source: source, origin: origin, priority: priority, path: path
+          }
+        end
+      end
+    end
+  end
+end

data/lib/arfi/commands/functions_creation.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Arfi
+  module Commands
+    # Function file creation helpers for {Arfi::Commands::Functions}.
+    module FunctionsCreation
+      private
+
+      # Ensure required function directories exist, creating them if necessary.
+      #
+      # @private
+      # @param [String?] adapter Database adapter name (nil for generic)
+      # @param [String?] schema PostgreSQL schema name (optional)
+      # @raise [Arfi::Errors::NoFunctionsDir] If db/functions directory doesn't exist
+      # @return [void]
+      def ensure_dirs!(adapter:, schema:)
+        root = Rails.root.join(ROOT_DIR)
+        raise Arfi::Errors::NoFunctionsDir unless root.directory?
+
+        FileUtils.mkdir_p(root.join(DEFAULT_SCHEMA))
+        return if adapter.nil?
+
+        adapter_root = root.join(adapter)
+        FileUtils.mkdir_p(adapter_root)
+        FileUtils.mkdir_p(adapter_root.join(DEFAULT_SCHEMA))
+        return unless adapter == 'postgresql'
+
+        sch = schema || DEFAULT_SCHEMA
+        FileUtils.mkdir_p(adapter_root.join(sch))
+      end
+
+      # Build the SQL function content, either from a custom template or from a skeleton.
+      #
+      # @private
+      # @param [String?] schema PostgreSQL schema name (optional)
+      # @param [String] function_name Function name
+      # @param [String] original_ref Original function reference as passed by the user
+      # @raise [StandardError] If adapter is unknown
+      # @return [String] SQL function body
+      def build_sql_function(schema, function_name, original_ref:)
+        return build_from_file(schema, function_name, original_ref: original_ref) if options[:template]
+
+        opt = adapter_opt
+        if opt.nil? || opt == 'postgresql'
+          build_postgresql_skeleton(schema, function_name)
+        elsif %w[mysql trilogy].include?(opt)
+          build_mysql_skeleton(function_name)
+        else
+          raise "Unknown adapter: #{opt}. Supported adapters: #{ADAPTERS.join(', ')}"
+        end
+      end
+
+      # Build SQL content by evaluating a user-supplied template file.
+      #
+      # @private
+      # @param [String?] schema PostgreSQL schema name (optional)
+      # @param [String] function_name Function name
+      # @param [String] original_ref Original function reference as passed by the user
+      # @return [String] Evaluated SQL content
+      def build_from_file(schema, function_name, original_ref:)
+        schema_name = resolve_schema_name(schema)
+        qualified_name = schema_name ? "#{schema_name}.#{function_name}" : function_name
+        evaluate_template(function_name, schema_name, qualified_name, original_ref)
+      end
+
+      # Write the SQL function content to disk, respecting --force option.
+      #
+      # @private
+      # @param [String?] schema PostgreSQL schema name (optional)
+      # @param [String] function_name Function name
+      # @param [String] content SQL function body to write
+      # @return [void]
+      def write_file(schema, function_name, content)
+        path = canonical_path(schema, function_name)
+        if File.exist?(path) && !options[:force]
+          puts "Already exists: #{rel(path)} (use --force to overwrite)"
+          return
+        end
+        File.write(path, content.to_s)
+        puts "Created: #{rel(path)}"
+      end
+
+      # Delete a function file from disk, searching known locations.
+      #
+      # @private
+      # @param [String?] schema PostgreSQL schema name (optional)
+      # @param [String] function_name Function name
+      # @return [void]
+      def remove_function_file(schema, function_name)
+        candidates = function_paths(schema, function_name)
+        path = candidates.find { |p| File.exist?(p) }
+        unless path
+          puts "Not found. Looked in:\n  - #{candidates.map { rel(_1) }.join("\n  - ")}"
+          return
+        end
+        FileUtils.rm(path)
+        puts "Deleted: #{rel(path)}"
+      end
+
+      # Evaluate a user-supplied Ruby template file to produce SQL content.
+      #
+      # @private
+      # @param [String] function_name Function name variable available in the template
+      # @param [String?] schema_name Schema name variable available in the template
+      # @param [String] qualified_name Qualified function name variable available in the template
+      # @param [String] original_ref Original function reference variable available in the template
+      # @return [Object] Evaluated template result (expected to be a String)
+      def evaluate_template(function_name, schema_name, qualified_name, original_ref)
+        tpl = File.read(options[:template])
+        RubyVM::InstructionSequence.compile(<<~RUBY).eval # steep:ignore
+          index_name     = #{function_name.inspect}
+          function_name  = #{function_name.inspect}
+          schema_name    = #{schema_name.inspect}
+          qualified_name = #{qualified_name.inspect}
+          original_ref   = #{original_ref.inspect}
+          #{tpl}
+        RUBY
+      end
+
+      # Build a default PostgreSQL function skeleton.
+      #
+      # @private
+      # @param [String?] schema PostgreSQL schema name (defaults to 'public')
+      # @param [String] function_name Function name
+      # @return [String] SQL skeleton
+      def build_postgresql_skeleton(schema, function_name)
+        sch = schema || DEFAULT_SCHEMA
+        qualified = "#{sch}.#{function_name}"
+        <<~SQL
+          CREATE OR REPLACE FUNCTION #{qualified}() RETURNS TEXT[]
+              LANGUAGE SQL
+              IMMUTABLE AS
+          $$
+              -- Function body here
+          $$
+        SQL
+      end
+
+      # Build a default MySQL function skeleton.
+      #
+      # @private
+      # @param [String] function_name Function name
+      # @return [String] SQL skeleton
+      def build_mysql_skeleton(function_name)
+        <<~SQL
+          -- MySQL note: you may need to DROP FUNCTION IF EXISTS #{function_name};
+          -- and ensure your connection allows multi-statements if you include both.
+          CREATE FUNCTION #{function_name} ()
+          RETURNS return_type
+          BEGIN
+            -- Function body here
+          END;
+        SQL
+      end
+    end
+  end
+end

data/lib/arfi/commands/functions_helpers.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Arfi
+  module Commands
+    # Shared helper methods for {Arfi::Commands::Functions}.
+    module FunctionsHelpers
+      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
+
+      # Validate that the --adapter option, if provided, is one of the supported adapters.
+      #
+      # @private
+      # @raise [Arfi::Errors::AdapterNotSupported] If adapter is not in the supported list
+      # @return [void]
+      def validate_adapter_option!
+        opt = adapter_opt
+        return if opt.nil?
+        raise Arfi::Errors::AdapterNotSupported unless ADAPTERS.map(&:to_s).include?(opt)
+      end
+
+      # Parse a function reference into an optional schema and function name.
+      #
+      # Accepts 'schema.function_name' or just 'function_name' form.
+      #
+      # @private
+      # @param [String] ref Function reference string
+      # @return [[ ::String?, ::String ]] Array of [schema, function_name]
+      def parse_function_ref(ref)
+        validate_function_ref!(ref)
+        parsed_schema, parsed_fn = ref.split('.', 2)
+        if parsed_fn.nil?
+          parsed_fn = parsed_schema
+          parsed_schema = nil
+        end
+        check_schema_conflict!(parsed_schema)
+        schema = schema_opt || parsed_schema
+        [schema, parsed_fn || '']
+      end
+
+      # Validate that schema and function name match the allowed identifier pattern.
+      #
+      # Schema-qualified functions are only allowed for PostgreSQL adapter.
+      #
+      # @private
+      # @param [String?] schema Schema name to validate (optional)
+      # @param [String] function_name Function name to validate
+      # @raise [ArgumentError] If identifiers are invalid
+      # @return [void]
+      def validate_identifiers!(schema, function_name)
+        raise ArgumentError, "Invalid function name: #{function_name.inspect}" unless IDENT.match?(function_name)
+        return if schema.nil?
+        raise ArgumentError, "Invalid schema name: #{schema.inspect}" unless IDENT.match?(schema)
+        return unless adapter_opt && adapter_opt != 'postgresql'
+
+        raise ArgumentError, 'Schema-qualified functions are only supported for PostgreSQL (adapter=postgresql).'
+      end
+
+      # Validate that a function reference is a non-empty string without path separators.
+      #
+      # @private
+      # @param [String] ref Function reference string
+      # @raise [ArgumentError] If reference is invalid
+      # @return [void]
+      def validate_function_ref!(ref)
+        raise ArgumentError, "Invalid function name: #{ref.inspect}" unless ref.is_a?(String)
+
+        sep = [File::SEPARATOR, File::ALT_SEPARATOR].compact
+        bad = ref.empty? || ref.include?('..') || sep.any? { |s| ref.include?(s) }
+        raise ArgumentError, "Invalid function name: #{ref.inspect}" if bad
+      end
+
+      # Raise if the schema is specified both inline and via the --schema option.
+      #
+      # @private
+      # @param [String?] parsed_schema Schema parsed from 'schema.function' form
+      # @raise [ArgumentError] If schema is specified twice
+      # @return [void]
+      def check_schema_conflict!(parsed_schema)
+        return unless schema_opt && parsed_schema
+
+        raise ArgumentError, "Schema specified twice (both 'schema.fn' and --schema). Pick one."
+      end
+
+      # Resolve the effective schema name, defaulting to 'public' for PostgreSQL/generic.
+      #
+      # @private
+      # @param [String?] schema User-provided schema name (optional)
+      # @return [String?] Resolved schema name or nil for MySQL/Trilogy
+      def resolve_schema_name(schema)
+        adapter = adapter_opt
+        adapter.nil? || adapter == 'postgresql' ? (schema || DEFAULT_SCHEMA) : nil
+      end
+
+      # Resolve the effective adapter from CLI option or Rails DB config.
+      #
+      # @private
+      # @raise [ArgumentError] If adapter cannot be inferred
+      # @return [String] Resolved adapter name
+      def resolve_adapter
+        adapter_opt || infer_adapter_from_config || raise(
+          ArgumentError,
+          'Could not infer adapter. Pass --adapter=[postgresql|mysql|trilogy].'
+        )
+      end
+
+      # Resolve the effective list of function files for a given adapter.
+      #
+      # @private
+      # @param [String] adapter Adapter name (postgresql, mysql, trilogy)
+      # @raise [Arfi::Errors::NoFunctionsDir] If db/functions directory doesn't exist
+      # @return [Array<Hash<Symbol, Object>>] Resolved function rows
+      def resolve_functions_for(adapter:)
+        root = Rails.root.join(ROOT_DIR)
+        raise Arfi::Errors::NoFunctionsDir unless root.directory?
+
+        candidates = collect_all_candidates(root, adapter)
+        by_key = group_candidates_by_key(candidates)
+        build_resolved_rows(by_key)
+      end
+
+      # Read the --adapter option value from CLI options.
+      #
+      # @private
+      # @return [String?] Adapter name or nil if not provided
+      def adapter_opt
+        options[:adapter]&.to_s
+      end
+
+      # Infer the database adapter from the Rails primary DB configuration.
+      #
+      # @private
+      # @raise [StandardError]
+      # @return [String?] Adapter name, or nil if inference fails
+      # @return [nil] if StandardError
+      def infer_adapter_from_config
+        cfg = primary_db_config
+        h = cfg&.configuration_hash
+        adapter = h && (h[:adapter] || h['adapter'])
+        adapter&.to_s
+      rescue StandardError
+        nil
+      end
+
+      # Read the --schema option value from CLI options.
+      #
+      # @private
+      # @return [String?] Schema name or nil if not provided
+      def schema_opt
+        options[:schema]&.to_s
+      end
+
+      # Get the primary database configuration for the current Rails environment.
+      #
+      # @private
+      # @return [Object] ActiveRecord database config object
+      def primary_db_config
+        cfgs =
+          if ActiveRecord::Base.respond_to?(:configurations) && ActiveRecord::Base.configurations
+            ActiveRecord::Base.configurations.configurations.select { _1.env_name == Rails.env }
+          else
+            [] # steep:ignore
+          end
+        cfgs.find { _1.name == 'primary' } || cfgs.first
+      end
+    end
+  end
+end

data/lib/arfi/commands/functions_paths.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Arfi
+  module Commands
+    # Path resolution helpers for {Arfi::Commands::Functions}.
+    module FunctionsPaths
+      private
+
+      # Resolve the canonical output path for a function file, respecting adapter option.
+      #
+      # @private
+      # @param [String?] schema Schema name (optional)
+      # @param [String] function_name Function name
+      # @return [String] Absolute path to the function file
+      def canonical_path(schema, function_name)
+        root = Rails.root.join(ROOT_DIR)
+        if adapter_opt.nil?
+          generic_canonical_path(root, schema, function_name)
+        else
+          adapter_canonical_path(root, schema, function_name)
+        end
+      end
+
+      # List all possible filesystem paths where a function file might exist, respecting adapter.
+      #
+      # @private
+      # @param [String?] schema Schema name (optional)
+      # @param [String] function_name Function name
+      # @raise [Arfi::Errors::AdapterNotSupported] If adapter is not supported
+      # @return [Array<String>] List of absolute paths to check
+      def function_paths(schema, function_name)
+        root = Rails.root.join(ROOT_DIR)
+        out = case adapter_opt
+              when nil then generic_function_paths(root, function_name)
+              when 'postgresql' then postgresql_function_paths(root, schema, function_name)
+              when 'mysql', 'trilogy' then mysql_function_paths(root, function_name)
+              else raise Arfi::Errors::AdapterNotSupported
+              end
+        out.uniq
+      end
+
+      # Build the canonical path for a generic (non-adapter) function.
+      #
+      # Generic functions can only target the 'public' schema.
+      #
+      # @private
+      # @param [Pathname] root Project root directory (Rails.root/db/functions)
+      # @param [String?] schema Schema name (must be nil or 'public')
+      # @param [String] function_name Function name
+      # @raise [ArgumentError] If schema is not public
+      # @return [String] Absolute canonical path
+      def generic_canonical_path(root, schema, function_name)
+        sch = schema || DEFAULT_SCHEMA
+        unless sch == DEFAULT_SCHEMA
+          raise ArgumentError,
+                "Generic functions can only target schema '#{DEFAULT_SCHEMA}'"
+        end
+        root.join(DEFAULT_SCHEMA, "#{function_name}.sql").to_s
+      end
+
+      # Build the canonical path for an adapter-specific function.
+      #
+      # @private
+      # @param [Pathname] root Project root directory (Rails.root/db/functions)
+      # @param [String?] schema Schema name (PostgreSQL only)
+      # @param [String] function_name Function name
+      # @raise [ArgumentError] If schema is provided for non-PostgreSQL adapter
+      # @raise [Arfi::Errors::AdapterNotSupported] If adapter is not supported
+      # @return [String] Absolute canonical path
+      def adapter_canonical_path(root, schema, function_name)
+        case adapter_opt
+        when 'postgresql'
+          root.join('postgresql', schema || DEFAULT_SCHEMA, "#{function_name}.sql").to_s
+        when 'mysql', 'trilogy'
+          raise ArgumentError, 'Schema-qualified functions are only supported for PostgreSQL.' if schema
+
+          root.join('mysql', DEFAULT_SCHEMA, "#{function_name}.sql").to_s
+        else
+          raise Arfi::Errors::AdapterNotSupported
+        end
+      end
+
+      # List file paths to check when looking for a generic function file.
+      #
+      # @private
+      # @param [Pathname] root Project root directory
+      # @param [String] function_name Function name
+      # @return [Array<String>] Ordered list of paths to check
+      def generic_function_paths(root, function_name)
+        [
+          root.join(DEFAULT_SCHEMA, "#{function_name}.sql").to_s,
+          root.join("#{function_name}.sql").to_s
+        ]
+      end
+
+      # List file paths to check when looking for a PostgreSQL function file.
+      #
+      # @private
+      # @param [Pathname] root Project root directory
+      # @param [String?] schema Schema name (optional)
+      # @param [String] function_name Function name
+      # @return [Array<String>] Ordered list of paths to check
+      def postgresql_function_paths(root, schema, function_name)
+        sch = schema || DEFAULT_SCHEMA
+        out = [
+          root.join('postgresql', sch, "#{function_name}.sql").to_s,
+          root.join('postgresql', DEFAULT_SCHEMA, "#{function_name}.sql").to_s,
+          root.join(DEFAULT_SCHEMA, "#{function_name}.sql").to_s,
+          root.join("#{function_name}.sql").to_s
+        ]
+        out.insert(2, root.join('postgresql', "#{function_name}.sql").to_s) if sch == DEFAULT_SCHEMA
+        out
+      end
+
+      # List file paths to check when looking for a MySQL/Trilogy function file.
+      #
+      # @private
+      # @param [Pathname] root Project root directory
+      # @param [String] function_name Function name
+      # @return [Array<String>] Ordered list of paths to check
+      def mysql_function_paths(root, function_name)
+        [
+          root.join('mysql', DEFAULT_SCHEMA, "#{function_name}.sql").to_s,
+          root.join('mysql', "#{function_name}.sql").to_s,
+          root.join(DEFAULT_SCHEMA, "#{function_name}.sql").to_s,
+          root.join("#{function_name}.sql").to_s
+        ]
+      end
+    end
+  end
+end