arfi 0.5.1 → 1.0.0

data/docscribe.yml

@@ -0,0 +1,92 @@
+---
+# Docscribe configuration file
+#
+# Docscribe works without this file — create it only for customization.
+#
+# Quick start:
+#   bundle exec docscribe lib          # check what would change
+#   bundle exec docscribe -a lib       # apply safe updates
+#   bundle exec docscribe -A lib       # rebuild all doc blocks
+
+emit:
+  # What to include in generated documentation
+  header: false                       # +MyClass#foo+ -> ReturnType
+  param_tags: true                    # @param tags
+  return_tag: true                    # @return tag
+  visibility_tags: true               # @private / @protected
+  raise_tags: true                    # @raise tags
+  rescue_conditional_returns: true    # @return [Type] if Error
+  attributes: false                   # @!attribute for attr_*
+
+  # Placeholder text for generated docs
+  include_default_message: true       # "Method documentation."
+  include_param_documentation: true    # "Param documentation."
+
+doc:
+  # Default text and formatting
+  default_message: "Method documentation."
+  param_documentation: "Param documentation."
+  param_tag_style: "type_name"        # "type_name" or "name_type"
+  sort_tags: true
+  tag_order: ["todo", "note", "api", "private", "protected", "param", "option", "yieldparam", "raise", "return"]
+
+inference:
+  # Type inference behavior
+  fallback_type: "Object"             # when uncertain
+  nil_as_optional: true               # String | nil => String?
+  treat_options_keyword_as_hash: true # options: keyword => Hash
+
+filter:
+  # Which methods and files to process
+  # Method format: "Container#method" (instance) or "Container.method" (class)
+  # Supports globs ("*#initialize") and regex ("/^MyApp::.*$/")
+  include: []
+  exclude: []
+  visibilities: ["public", "protected", "private"]
+  scopes: ["instance", "class"]
+
+  files:
+    # File paths relative to project root (globs or /regex/)
+    include: []
+    exclude: ["spec"]
+
+methods:
+  # Override defaults per scope and visibility.
+  # Empty {} means "use values from `doc` section".
+  #
+  # Example:
+  #   instance:
+  #     public:
+  #       default_message: "Public API."
+  #     private:
+  #       return_tag: false
+  instance:
+    public: {}
+    protected: {}
+    private: {}
+  class:
+    public: {}
+    protected: {}
+    private: {}
+
+rbs:
+  # Use RBS signatures for better types (requires `gem "rbs"`)
+  enabled: true
+  sig_dirs: ["sig"]
+  collection_dirs: []                 # auto-discovered from --rbs-collection
+  collapse_generics: false            # Hash<Symbol, String> => Hash
+  collection: true                   # auto-discover from rbs_collection.lock.yaml
+
+sorbet:
+  # Use Sorbet inline sigs and RBI files for better types
+  enabled: false
+  rbi_dirs: ["sorbet/rbi", "rbi"]
+  collapse_generics: false
+
+plugins:
+  # Load custom plugins
+  # Example:
+  #   require:
+  #     - ./docscribe_plugins
+  #     - docscribe-rails-associations
+  require: []

data/gemfiles/rails_6_0.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec path: '..'
+
+gem 'benchmark'
+gem 'bigdecimal'
+gem 'mysql2'
+gem 'pg'
+gem 'rails', '~> 6.0'

data/gemfiles/rails_6_1.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec path: '..'
+
+gem 'benchmark'
+gem 'bigdecimal'
+gem 'mysql2'
+gem 'pg'
+gem 'rails', '~> 6.1'

data/gemfiles/rails_7_0.gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec path: '..'
+
+gem 'mysql2'
+gem 'pg'
+gem 'rails', '~> 7.0.0'

data/gemfiles/rails_7_1.gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec path: '..'
+
+gem 'mysql2'
+gem 'pg'
+gem 'rails', '~> 7.1.0'
+gem 'trilogy'

data/gemfiles/rails_7_2.gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec path: '..'
+
+gem 'mysql2'
+gem 'pg'
+gem 'rails', '~> 7.2.0'
+gem 'trilogy'

data/gemfiles/rails_8_0.gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec path: '..'
+
+gem 'mysql2'
+gem 'pg'
+gem 'rails', '~> 8.0'
+gem 'trilogy'

data/gemfiles/rails_8_1.gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec path: '..'
+
+gem 'mysql2'
+gem 'pg'
+gem 'rails', '~> 8.1'
+gem 'trilogy'

data/lib/arfi/cli.rb

@@ -1,23 +1,38 @@
 # frozen_string_literal: true
 
 require 'thor'
-require_relative 'commands/project'
-require_relative 'commands/f_idx'
+require_relative 'commands/init'
+require_relative 'commands/functions'
 
-# steep:ignore:start
 module Arfi
-  # Top level CLI class
+  # Top-level CLI entrypoint for the `arfi` executable.
+  #
+  # It wires new command groups and keeps backward-compatible aliases:
+  # - `arfi init`      (preferred)
+  # - `arfi functions` (preferred)
+  # - `arfi project`   (alias for init)
+  # - `arfi f_idx`     (alias for functions)
+  #
+  # @api public
   class CLI < Thor
-    desc 'project [COMMAND]', 'Project specific commands.'
-    subcommand 'project', Commands::Project
+    desc 'init [COMMAND]', 'Initialize ARFI directories (new command). Default: create'
+    subcommand 'init', Arfi::Commands::Init
 
-    desc 'f_idx [COMMAND]', 'Command to handle functions.'
-    subcommand 'f_idx', Commands::FIdx
+    desc 'project [COMMAND]', 'Alias for `arfi init` (backward compatible).'
+    subcommand 'project', Arfi::Commands::Init
+
+    desc 'functions [COMMAND]', 'Manage SQL function files (new command). Default: list'
+    subcommand 'functions', Arfi::Commands::Functions
+
+    desc 'f_idx [COMMAND]', 'Alias for `arfi functions` (backward compatible).'
+    subcommand 'f_idx', Arfi::Commands::Functions
 
     desc 'version', 'Print the version'
+    # Print the gem version to stdout.
+    #
+    # @return [Integer]
     def version
       $stdout.write(Arfi::VERSION, "\n")
     end
   end
 end
-# steep:ignore:end

data/lib/arfi/commands/f_idx.rb

@@ -1,238 +1,13 @@
 # frozen_string_literal: true
 
-require 'thor'
-require 'rails'
-require File.expand_path('config/environment', Dir.pwd)
+require_relative 'functions'
 
 module Arfi
   module Commands
     # +Arfi::Commands::FIdx+ module contains commands for manipulating functional index in Rails project.
-    class FIdx < Thor
-      ADAPTERS = %i[postgresql mysql].freeze
-
-      # steep:ignore:start
-      desc 'create FUNCTION_NAME [--template=template_file --adapter=adapter]', 'Initialize the functional index'
-      option :template, type: :string, banner: 'template_file',
-                        desc: 'Path to the template file. See `README.md` for details.'
-      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::FIdx#create+                        -> void
-      #
-      # This command is used to create the functional index.
-      #
-      # @example
-      #   bundle exec arfi f_idx create some_function
-      #
-      # ARFI also supports the use of custom templates for SQL functions, but now there are some restrictions and rules
-      # according to which it is necessary to describe the function. First, the function must be written in a
-      # Ruby-compatible syntax: the file name is not so important, but the name for the function name must be
-      # interpolated with the +index_name+ variable name, and the function itself must be placed in the HEREDOC
-      # statement. Below is an example file.
-      #
-      # @example
-      #   # ./template/my_custom_template
-      #   <<~SQL
-      #   CREATE OR REPLACE FUNCTION #{index_name}() RETURNS TEXT[]
-      #     LANGUAGE SQL
-      #     IMMUTABLE AS
-      #   $$
-      #     -- Function body here
-      #   $$
-      #   SQL
-      #
-      # To use a custom template, add the --template flag.
-      #
-      # @example
-      #   bundle exec arfi f_idx create some_function --template ./template/my_custom_template
-      #
-      # @param index_name [String] Name of the index.
-      # @return [void]
-      # @raise [Arfi::Errors::InvalidSchemaFormat] if ActiveRecord.schema_format is not :ruby
-      # @raise [Arfi::Errors::NoFunctionsDir] if there is no `db/functions` directory
-      # @see Arfi::Commands::FIdx#validate_schema_format!
-      def create(index_name)
-        validate_schema_format!
-        content = build_sql_function(index_name)
-        create_function_file(index_name, content)
-      end
-
-      # steep:ignore:start
-      desc 'destroy INDEX_NAME [--revision=revision --adapter=adapter]', 'Delete the functional index.'
-      option :revision, type: :string, banner: 'revision', desc: 'Revision of the function.'
-      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::FIdx#destroy+                        -> void
-      #
-      # This command is used to delete the functional index.
-      #
-      # @example
-      #   bundle exec arfi f_idx destroy some_function [revision index (just an integer, 1 is by default)]
-      # @param index_name [String] Name of the index.
-      # @return [void]
-      # @raise [Arfi::Errors::InvalidSchemaFormat] if ActiveRecord.schema_format is not :ruby
-      def destroy(index_name)
-        validate_schema_format!
-
-        revision = Integer(options[:revision] || '01') # steep:ignore NoMethod
-        revision = "0#{revision}"
-        FileUtils.rm("#{functions_dir}/#{index_name}_v#{revision}.sql")
-        puts "Deleted: #{functions_dir}/#{index_name}_v#{revision}.sql"
-      end
-
-      private
-
-      # +Arfi::Commands::FIdx#validate_schema_format!+                        -> void
-      #
-      # Helper method to validate the schema format.
-      #
-      # @!visibility private
-      # @private
-      # @raise [Arfi::Errors::InvalidSchemaFormat] if ActiveRecord.schema_format is not :ruby.
-      # @return [nil] if the schema format is valid.
-      def validate_schema_format!
-        raise Arfi::Errors::InvalidSchemaFormat unless ActiveRecord.schema_format == :ruby # steep:ignore NoMethod
-      end
-
-      # +Arfi::Commands::FIdx#build_sql_function+                        -> String
-      #
-      # Helper method to build the SQL function.
-      #
-      # @!visibility private
-      # @private
-      # @param index_name [String] Name of the index.
-      # @return [String] SQL function body.
-      def build_sql_function(index_name) # rubocop:disable Metrics/MethodLength
-        return build_from_file(index_name) if options[:template] # steep:ignore NoMethod
-
-        unless options[:adapter] # steep:ignore NoMethod
-          return <<~SQL
-            CREATE OR REPLACE FUNCTION #{index_name}() RETURNS TEXT[]
-                LANGUAGE SQL
-                IMMUTABLE AS
-            $$
-                -- Function body here
-            $$
-          SQL
-        end
-
-        case options[:adapter] # steep:ignore NoMethod
-        when 'postgresql'
-          <<~SQL
-            CREATE OR REPLACE FUNCTION #{index_name}() RETURNS TEXT[]
-                LANGUAGE SQL
-                IMMUTABLE AS
-            $$
-                -- Function body here
-            $$
-          SQL
-        when 'mysql'
-          <<~SQL
-            CREATE FUNCTION #{index_name} ()
-            RETURNS return_type
-            BEGIN
-              -- Function body here
-            END;
-          SQL
-        else
-          # steep:ignore:start
-          raise "Unknown adapter: #{options[:adapter]}. Supported adapters: #{ADAPTERS.join(', ')}"
-          # steep:ignore:end
-        end
-      end
-
-      # +Arfi::Commands::FIdx#build_from_file+                          -> String
-      #
-      # Helper method to build the SQL function. Used with flag `--template`.
-      #
-      # @!visibility private
-      # @private
-      # @param index_name [String] Name of the index.
-      # @return [String] SQL function body.
-      # @see Arfi::Commands::FIdx#create
-      # @see Arfi::Commands::FIdx#build_sql_function
-      def build_from_file(index_name)
-        # steep:ignore:start
-        RubyVM::InstructionSequence.compile("index_name = '#{index_name}'; #{File.read(options[:template])}").eval
-        # steep:ignore:end
-      end
-
-      # +Arfi::Commands::FIdx#create_function_file+                        -> void
-      #
-      # Helper method to create the index file.
-      #
-      # @!visibility private
-      # @private
-      # @param index_name [String] Name of the index.
-      # @param content [String] SQL function body.
-      # @return [void]
-      def create_function_file(index_name, content)
-        existing_files = Dir.glob("#{functions_dir}/#{index_name}*.sql")
-
-        return write_file(index_name, content, 1) if existing_files.empty?
-
-        latest_version = extract_latest_version(existing_files)
-        write_file(index_name, content, latest_version.succ)
-      end
-
-      # +Arfi::Commands::FIdx#extract_latest_version+                        -> Integer
-      #
-      # Helper method to extract the latest version of the index.
-      #
-      # @!visibility private
-      # @private
-      # @param files [Array<String>] List of files.
-      # @return [String] Latest version of the index.
-      def extract_latest_version(files)
-        version_numbers = files.map do |file|
-          File.basename(file)[/\w+_v(\d+)\.sql/, 1]
-        end.compact
-
-        version_numbers.max
-      end
-
-      # +Arfi::Commands::FIdx#write_file+                        -> void
-      #
-      # Helper method to write the index file.
-      #
-      # @!visibility private
-      # @private
-      # @param index_name [String] Name of the index.
-      # @param content [String] SQL function body.
-      # @param version [String|Integer] Version of the index.
-      # @return [void]
-      def write_file(index_name, content, version)
-        version_str = format('%02d', version)
-        path = "#{functions_dir}/#{index_name}_v#{version_str}.sql"
-        File.write(path, content.to_s)
-        puts "Created: #{path}"
-      end
-
-      # +Arfi::Commands::FIdx#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::FIdx.
+    # @deprecated
+    FIdx = Functions
   end
 end

data/lib/arfi/commands/functions.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'rails'
+require 'fileutils'
+require 'json'
+
+require_relative 'functions_helpers'
+require_relative 'functions_creation'
+require_relative 'functions_paths'
+require_relative 'functions_rendering'
+require_relative 'functions_candidates'
+
+module Arfi
+  module Commands
+    ADAPTERS = %i[postgresql mysql trilogy].freeze
+    ROOT_DIR = 'db/functions'
+    DEFAULT_SCHEMA = 'public'
+    IDENT = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.freeze
+
+    # Thor CLI for managing SQL function files.
+    class Functions < Thor
+      include FunctionsHelpers
+      include FunctionsCreation
+      include FunctionsPaths
+      include FunctionsRendering
+      include FunctionsCandidates
+
+      default_task :list
+
+      # UX aliases
+      map %w[ls] => :list
+      map %w[rm delete del] => :destroy
+      map %w[new add] => :create
+
+      # steep:ignore:start
+      desc(
+        'create FUNCTION_NAME [--schema=schema --template=template_file --adapter=adapter --force]',
+        "Create (or overwrite with --force) a SQL function file.\n  " \
+        "Generic public:      db/functions/public/<function>.sql\n  " \
+        "PostgreSQL public:   db/functions/postgresql/public/<function>.sql\n  " \
+        "PostgreSQL schema:   db/functions/postgresql/<schema>/<function>.sql\n" \
+        "Schema can be passed as 'schema.function' or via --schema (PostgreSQL only)."
+      )
+      option :schema, type: :string, banner: 'schema',
+                      desc: "PostgreSQL schema name (alternative to 'schema.function')."
+      option :template, type: :string, banner: 'template_file',
+                        desc: 'Path to the template file. See README.md for details.'
+      option :adapter, type: :string,
+                       desc: "Specify database adapter. Available adapters: #{ADAPTERS.join(', ')}",
+                       banner: 'adapter'
+      option :force, type: :boolean, default: false,
+                     desc: 'Overwrite existing function file if it already exists.'
+      # steep:ignore:end
+      # Create (or overwrite with --force) a SQL function file in the appropriate directory.
+      #
+      # @param [String] function_ref Function reference string (e.g. 'my_func' or 'schema.my_func')
+      # @return [void]
+      def create(function_ref)
+        validate_schema_format!
+        validate_adapter_option!
+
+        schema, function_name = parse_function_ref(function_ref)
+        validate_identifiers!(schema, function_name)
+
+        ensure_dirs!(adapter: adapter_opt, schema: schema)
+
+        content = build_sql_function(schema, function_name, original_ref: function_ref)
+        write_file(schema, function_name, content)
+      end
+
+      # steep:ignore:start
+      desc(
+        'destroy FUNCTION_NAME [--schema=schema --adapter=adapter]',
+        'Delete a SQL function file (supports both new and legacy locations).'
+      )
+      option :schema, type: :string, banner: 'schema',
+                      desc: "PostgreSQL schema name (alternative to 'schema.function')."
+      option :adapter, type: :string,
+                       desc: "Specify database adapter. Available adapters: #{ADAPTERS.join(', ')}",
+                       banner: 'adapter'
+      # steep:ignore:end
+      # Delete a SQL function file from disk (supports both new and legacy locations).
+      #
+      # @param [String] function_ref Function reference string (e.g. 'my_func' or 'schema.my_func')
+      # @return [void]
+      def destroy(function_ref)
+        validate_schema_format!
+        validate_adapter_option!
+
+        schema, function_name = parse_function_ref(function_ref)
+        validate_identifiers!(schema, function_name)
+
+        ensure_dirs!(adapter: adapter_opt, schema: schema)
+
+        remove_function_file(schema, function_name)
+      end
+
+      # steep:ignore:start
+      desc(
+        'list [--adapter=adapter] [--format=table|paths|json] [--all]',
+        "List SQL function files ARFI would load for the chosen adapter.\n" \
+        "Default: inferred adapter from Rails config. Default output: table.\n" \
+        '--all shows shadowed/overridden candidates too.'
+      )
+      option :adapter, type: :string,
+                       desc: "Specify database adapter. Available adapters: #{ADAPTERS.join(', ')}",
+                       banner: 'adapter'
+      option :format, type: :string, default: 'table',
+                      desc: 'Output format: table, paths, json'
+      option :all, type: :boolean, default: false,
+                   desc: 'Show all candidates (including overridden ones), not just the effective set.'
+      # steep:ignore:end
+      # List SQL function files ARFI would load for the chosen adapter.
+      #
+      # @return [void]
+      def list
+        validate_schema_format!
+        validate_adapter_option!
+
+        adapter = resolve_adapter
+        rows = resolve_functions_for(adapter: adapter)
+
+        render_list(rows)
+      end
+    end
+  end
+end