yard-is-sequel 0.8.0

data/README.md

@@ -0,0 +1,245 @@
+# yard-is-sequel
+
+YARD plugin for documenting Sequel ORM models.
+
+## Overview
+
+`yard-is-sequel` is a YARD plugin that automatically documents Sequel ORM models by extracting information about database fields, associations, and model definitions directly from your Ruby code. It generates comprehensive documentation without requiring manual annotations for basic Sequel features.
+
+## Features
+
+- **Automatic Field Documentation**: Extracts database column information from Sequel models
+- **Association Detection**: Documents `many_to_one`, `one_to_many`, and `many_to_many` associations
+- **Sequel Model Tagging**: Automatically identifies and tags classes that inherit from `Sequel::Model`
+- **Migration Support**: Reads database schema from Sequel migrations
+- **Integration with YARD**: Seamlessly integrates with existing YARD documentation workflows
+
+## Installation
+
+### As a Gem
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'yard-is-sequel', '~> 0.8'
+```
+
+Or install directly:
+
+```bash
+gem install yard-is-sequel
+```
+
+### For Development
+
+Add to your project's `.gemspec`:
+
+```ruby
+spec.add_development_dependency 'yard-is-sequel', '~> 0.8'
+```
+
+## Usage
+
+### Basic Usage
+
+Run YARD with the plugin enabled:
+
+```bash
+$ yardoc --plugin is-sequel
+```
+
+### Using `.yardopts` File
+
+Add the plugin to your `.yardopts` file:
+
+```
+--plugin is-sequel
+--markup markdown
+--output-dir ./doc
+```
+
+### Environment Configuration
+
+For field detection to work, you need to set the path to your Sequel migrations:
+
+```bash
+export SEQUEL_MIGRATIONS_DIR=/path/to/your/migrations
+```
+
+Or set it temporarily:
+
+```bash
+SEQUEL_MIGRATIONS_DIR=/path/to/migrations yardoc --plugin is-sequel
+```
+
+## How It Works
+
+### Database Fields
+
+The plugin processes tables defined via `set_dataset` or `dataset=`. It:
+- Applies migrations to an in-memory SQLite database
+- Extracts column names, types, and nullability constraints
+- Documents each field as an attribute with proper type annotations
+
+Example model:
+```ruby
+class User < Sequel::Model
+  set_dataset :users
+end
+```
+
+Generated documentation will include all fields from the `users` table.
+
+### Associations
+
+The plugin detects and documents Sequel associations:
+
+```ruby
+class User < Sequel::Model
+  many_to_one :organization
+  one_to_many :posts
+  many_to_many :roles
+end
+```
+
+Each association is documented as an attribute with:
+- Appropriate return types
+- Association type tags
+- Grouping under "Sequel Associations"
+
+### Model Detection
+
+Classes inheriting from `Sequel::Model` are automatically tagged as Sequel models.
+
+## Configuration
+
+### Migration Directory
+
+Set the environment variable for migrations:
+```bash
+export SEQUEL_MIGRATIONS_DIR=./db/migrations
+```
+
+### Plugin Options
+
+Currently, the plugin supports the following implicit configurations:
+- Database fields are extracted only when `SEQUEL_MIGRATIONS_DIR` is set
+- All Sequel models in processed files are documented
+- Associations are automatically detected from method calls
+
+## Examples
+
+### Full Example Model
+
+```ruby
+# app/models/user.rb
+class User < Sequel::Model(:users)
+  # These will be documented automatically
+  many_to_one :organization
+  one_to_many :posts
+  many_to_many :permissions
+  
+  # Custom methods are preserved
+  def full_name
+    "#{first_name} #{last_name}"
+  end
+end
+```
+
+### Generated Documentation
+
+The plugin generates documentation that includes:
+
+1. **Fields Section**: Database columns with types
+2. **Associations Section**: All Sequel associations
+3. **Methods Section**: Custom methods (preserved from existing YARD docs)
+
+## Development
+
+### Setting Up Development Environment
+
+```bash
+git clone https://github.com/inat-get/yard-is-sequel.git
+cd yard-is-sequel
+bundle install
+```
+
+### Running Tests
+
+```bash
+bundle exec rake spec
+```
+
+### Project Structure
+
+```
+lib/
+├── yard-is-sequel.rb          # Main plugin file
+├── yard-is-sequel/
+│   ├── info.rb               # Plugin metadata
+│   ├── models.rb             # Model detection handler
+│   ├── associations.rb       # Association handler
+│   └── fields.rb             # Field extraction handler
+spec/                         # Test files
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for your changes
+4. Ensure all tests pass
+5. Submit a pull request
+
+## Requirements
+
+- Ruby >= 3.4
+- YARD >= 0.9
+- Sequel >= 5.100
+- SQLite3 >= 2.9 (for migration processing)
+
+## Limitations
+
+- Field detection requires Sequel migrations
+- Currently supports SQLite for schema extraction (but works with any DB via Sequel)
+- Complex association options might not be fully parsed
+- Database views are not currently supported
+
+## Troubleshooting
+
+### Fields Not Appearing
+- Ensure `SEQUEL_MIGRATIONS_DIR` is set correctly
+- Verify migrations can be applied without errors
+- Check that your models use `set_dataset` or `dataset=`
+
+### Associations Not Documented
+- Verify association method calls are at the class level
+- Check for syntax errors in association definitions
+- Ensure the plugin is loaded (check YARD output)
+
+### Plugin Not Loading
+- Verify YARD version compatibility
+- Check `.yardopts` file for correct plugin name
+- Try running with `--debug` flag for more information
+
+## License
+
+This project is licensed under the GPL-3.0-or-later License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+Ivan Shikhalev
+
+## Repository
+
+https://github.com/inat-get/yard-is-sequel
+
+## Acknowledgments
+
+- YARD team for the excellent documentation tool
+- Sequel ORM maintainers
+- Contributors and users of the plugin
+
+---
+
+*Note: This plugin is designed to complement existing YARD documentation. It automatically adds Sequel-specific documentation but doesn't interfere with manually written documentation.*

data/lib/yard-is-sequel/associations.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require_relative "info"
+
+class IS::YARD::Sequel::AssociationsHandler < YARD::Handlers::Ruby::Base
+  handles method_call(:many_to_one)
+  handles method_call(:one_to_many)
+  handles method_call(:many_to_many)
+  namespace_only
+
+  def process
+    # Получаем имя ассоциации
+    first_param = statement.parameters.first
+    assoc_name = first_param.jump(:ident, :string_content).source.to_sym
+
+    # Определяем тип ассоциации
+    assoc_type = statement.method_name.source.to_sym
+
+    # Извлекаем опции
+    options = extract_options
+
+    # Определяем класс ассоциации
+    assoc_class = determine_association_class(assoc_name, options)
+
+    # Создаем атрибут в документации
+    register_attribute(assoc_name, assoc_type, assoc_class)
+  end
+
+  private
+
+  def extract_options
+    options = {}
+
+    # Ищем хэш опций в параметрах
+    statement.parameters.each do |param|
+      next unless param && param.respond_to?(:type)
+
+      if param.type == :hash || param.type == :assoclist || param.type == :list
+        process_hash_node(param, options)
+      elsif param.type == :bare_assoc_hash
+        process_bare_assoc_hash(param, options)
+      end
+    end
+
+    options
+  end
+
+  def process_hash_node(hash_node, options)
+    if hash_node.type == :hash
+      hash_node.children.each do |child|
+        next unless child.respond_to?(:type) && child.type == :assoc
+
+        key_node, value_node = child.children
+        process_assoc_pair(key_node, value_node, options) if key_node && value_node
+      end
+    elsif hash_node.type == :assoclist || hash_node.type == :list
+      hash_node.children.each do |child|
+        if child.respond_to?(:type) && child.type == :assoc && child.children.size >= 2
+          process_assoc_pair(child.children[0], child.children[1], options)
+        end
+      end
+    end
+  end
+
+  def process_bare_assoc_hash(hash_node, options)
+    hash_node.children.each do |child|
+      if child.respond_to?(:type) && child.type == :assoc && child.children.size >= 2
+        key_node, value_node = child.children
+        process_assoc_pair(key_node, value_node, options)
+      end
+    end
+  end
+
+  def process_assoc_pair(key_node, value_node, options)
+    return unless key_node && value_node
+
+    key_name = extract_key_name(key_node)
+    return unless key_name
+
+    options[key_name] = parse_option_value(value_node)
+  end
+
+  def extract_key_name(key_node)
+    return unless key_node.respond_to?(:source)
+
+    key_source = key_node.source
+    key_source = key_source.to_s
+      .gsub(/^:/, "")
+      .gsub(/:$/, "")
+      .gsub(/^["']|["']$/, "")
+
+    key_source.to_sym
+  end
+
+  def parse_option_value(value_node)
+    return nil unless value_node && value_node.respond_to?(:source)
+
+    source = value_node.source
+
+    case value_node.type
+    when :symbol_literal, :symbol
+      source = source.to_s.sub(/^:/, "")
+    when :string_literal
+      source = source.gsub(/^['"]|['"]$/, "")
+    when :dyna_symbol
+      source = source.to_s.sub(/^:/, "").gsub(/^["']|["']$/, "")
+    end
+
+    source
+  end
+
+  def determine_association_class(assoc_name, options)
+    class_name = options[:class] || options[:class_name]
+
+    if class_name
+      class_name = class_name.to_s
+      class_name = class_name.gsub(/^['"]|['"]$/, "")
+      return class_name
+    end
+
+    class_name = assoc_name.to_s
+      .sub(/s$/, "")
+      .split("_")
+      .map(&:capitalize)
+      .join
+
+    class_name
+  end
+
+  def register_attribute(name, assoc_type, assoc_class)
+    # Определяем тип атрибута: rw для many_to_one (read/write), r для остальных (read only)
+    # attr_type = (assoc_type == :many_to_one) ? "rw" : "r"
+
+    # Определяем возвращаемый тип
+    return_type = case assoc_type
+      when :many_to_one
+        "#{assoc_class}, nil"
+      when :one_to_many, :many_to_many
+        "Sequel::Dataset, Array<#{assoc_class}>"
+      end
+
+    # Создаем объект метода с директивой @!attribute
+    method_obj = YARD::CodeObjects::MethodObject.new(
+      namespace,
+      name,
+      :instance
+    )
+    method_obj.is_attribute = true
+    method_obj.group = 'Sequel Associations'
+    namespace.attributes[:instance][name] = {
+      read: method_obj,
+      write: method_obj
+    }
+
+    # Формируем документацию с директивой @!attribute
+    docstring_parts = []
+
+    # Директива @!attribute должна быть первой
+    # docstring_parts << "@!attribute [#{attr_type}]"
+    docstring_parts << "@return [#{return_type}]"
+
+    # Описание
+    docstring_parts << "Sequel #{assoc_type.to_s.gsub('_', '-')} association."
+
+    # Примеры
+    # example_content = generate_example(name, assoc_type, assoc_class)
+    # if example_content && !example_content.empty?
+    #   docstring_parts << ""
+    #   docstring_parts << "@example"
+    #   example_content.lines.each do |line|
+    #     docstring_parts << "  #{line.chomp}"
+    #   end
+    # end
+
+    method_obj.docstring = docstring_parts.join("\n")
+
+    # Добавляем тег для фильтрации
+    method_obj.add_tag(YARD::Tags::Tag.new(:sequel_association, assoc_type.to_s))
+
+    # Регистрируем в YARD
+    register(method_obj)
+
+    log.debug "[Sequel Plugin] Added association attribute: #{namespace}##{name} (#{assoc_type})"
+  end
+
+  def generate_example(name, assoc_type, assoc_class)
+    namespace_name = namespace.name.to_s
+    model_name = namespace_name.split("::").last.downcase
+
+    case assoc_type
+    when :many_to_one
+      <<~EXAMPLE.chomp
+        #{model_name}.#{name}          # => #{assoc_class} instance or nil
+        #{model_name}.#{name} = #{assoc_class}.first
+      EXAMPLE
+    when :one_to_many
+      singular_name = name.to_s.chomp("s")
+      <<~EXAMPLE.chomp
+        #{model_name}.#{name}          # => Dataset of #{assoc_class} objects
+        #{model_name}.add_#{singular_name}(#{assoc_class}.new)
+      EXAMPLE
+    when :many_to_many
+      singular_name = name.to_s.chomp("s")
+      <<~EXAMPLE.chomp
+        #{model_name}.#{name}          # => Dataset of #{assoc_class} objects
+        #{model_name}.add_#{singular_name}(#{assoc_class}.first)
+        #{model_name}.#{name}_dataset  # Many-to-many through join table
+      EXAMPLE
+    end
+  end
+end

data/lib/yard-is-sequel/fields.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'sequel'
+
+class IS::YARD::Sequel::FieldsHandler < YARD::Handlers::Ruby::Base
+
+  handles method_call(:set_dataset)
+  handles method_call(:dataset=)
+
+  def process
+    table_name = statement.parameters.first.jump(:symbol, :string).source.delete(':"\'')
+    database = self.class.database
+    return unless database
+    table_schema = database.schema(table_name)
+    return unless table_schema
+
+    table_schema.each do |column_name, info|
+      type = [ map_type(info[:db_type]) ]
+      type << 'nil' unless info[:allow_null] == false
+
+      object = YARD::CodeObjects::MethodObject.new(namespace, column_name) do |o|
+        o.source = statement.source
+        o.parameters = []
+        o.docstring = 'Sequel data field'
+        o.docstring.add_tag YARD::Tags::Tag::new(:return, '', type)
+        o.docstring.add_tag YARD::Tags::Tag::new(:sequel_field, '')
+        o.is_attribute = true
+        o.group = 'Sequel Fields'
+      end
+      register object
+      namespace.attributes[:instance][column_name] = {
+        read: object,
+        write: object
+      }
+    end
+  end
+
+  private
+
+  def map_type source
+    case source.to_s.downcase
+    when 'integer'
+      'Integer'
+    when 'float', 'double precision'
+      'Float'
+    when /^char/, /^varchar/, 'text'
+      'String'
+    when 'timestamp', 'datetime', 'time'
+      'Time'
+    when 'boolean'
+      'Boolean'
+    else
+      source
+    end
+  end
+
+  class << self
+
+    def database
+      @database ||= setup_database
+    end
+
+    private
+
+    def setup_database
+      # return unless defined?($SEQUEL_MIGRATIONS_DIR) && $SEQUEL_MIGRATIONS_DIR
+      begin
+        Sequel.extension :migration
+        db = Sequel.sqlite
+        Sequel::Migrator::run db, ENV['SEQUEL_MIGRATIONS_DIR']
+        db
+      rescue
+        nil
+      end
+    end
+
+  end
+
+end

data/lib/yard-is-sequel/info.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module IS; end
+module IS::YARD; end
+module IS::YARD::Sequel; end
+
+module IS::YARD::Sequel::Info
+
+  NAME     = 'yard-is-sequel'
+  VERSION  = '0.8.0'
+  SUMMARY  = 'YARD-plugin for Sequel-models documenting'
+  AUTHOR   = 'Ivan Shikhalev'
+  LICENSE  = 'GPL-3.0-or-later'
+  HOMEPAGE = 'https://github.com/inat-get/yard-is-sequel'
+
+end

data/lib/yard-is-sequel/models.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# require "yard"
+
+require_relative "info"
+
+class IS::YARD::Sequel::ModelHandler < YARD::Handlers::Ruby::ClassHandler
+  handles :class
+
+  def process
+    # Проверяем, наследуется ли класс от Sequel::Model
+    return unless sequel_model?
+
+    # Добавляем тег к классу, что это Sequel модель
+    # Используем пустое значение для тега
+    namespace.add_tag(YARD::Tags::Tag.new(:sequel_model, ""))
+
+    log.debug "[Sequel Plugin] Detected Sequel model: #{namespace}"
+  end
+
+  private
+
+  def sequel_model?
+    # Проверяем наличие суперкласса
+    superclass = statement.superclass
+    return false unless superclass
+
+    # Получаем исходный код суперкласса как строку
+    superclass_source = superclass.source
+
+    # Проверяем разные варианты записи Sequel::Model:
+    # 1. class User < Sequel::Model
+    # 2. class User < Sequel::Model(:users)
+    # 3. class User < Sequel::Model(DB[:users])
+
+    # Простая проверка по подстроке
+    superclass_source =~ /Sequel::Model/
+  end
+
+end

data/lib/yard-is-sequel.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "yard-is-sequel/info"
+
+module IS::YARD::Sequel
+  def self.init
+    register_tags
+  end
+
+  def self.register_tags
+    YARD::Tags::Library.define_tag 'Sequel Model', :sequel_model
+    YARD::Tags::Library.define_tag "Sequel Field", :sequel_field
+    YARD::Tags::Library.define_tag 'Sequel Association', :sequel_association
+  end
+end
+
+require_relative 'yard-is-sequel/associations'
+require_relative 'yard-is-sequel/models'
+require_relative 'yard-is-sequel/fields'
+
+YARD::Handlers::Processor.register_handler_namespace(:sequel, IS::YARD::Sequel)
+
+IS::YARD::Sequel.init