develoz-rails 0.1.0

data/lib/generators/develoz/ci/templates/config/ci.rb.tt

@@ -0,0 +1,23 @@
+# Run using bin/ci
+
+CI.run do
+  step "Setup", "bin/setup --skip-server"
+
+  step "Style: Ruby", "bin/rubocop"
+  step "Style: Reek", "bin/reek app lib"
+  step "Style: Flay", "bin/flay --mass 300 app lib"
+
+  step "Style: Biome", "yarn lint"
+  step "Style: Stylelint", "yarn lint:css"
+  step "Style: haml-lint", "bin/haml-lint app"
+  step "Style: markdownlint", "yarn lint:md"
+  step "Style: yamllint", "yamllint ."
+
+  step "Security: Gem audit", "bin/bundler-audit"
+  step "Security: Importmap audit", "bin/importmap audit"
+  step "Security: Brakeman", "bin/brakeman --quiet --no-pager --exit-on-warn --exit-on-error"
+
+  step "Tests: RSpec", "bundle exec rspec"
+
+  # Coverage gate: enforced by SimpleCov in spec/spec_helper.rb (100% line + branch)
+end

data/lib/generators/develoz/concerns/concerns_generator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "develoz"
+
+module Develoz
+  module Generators
+    class ConcernsGenerator < Develoz::Generators::Base
+      def self.source_root
+        File.expand_path("templates", __dir__)
+      end
+
+      def create_concerns
+        template "app/models/concerns/searchable_concern.rb.tt", "app/models/concerns/searchable_concern.rb"
+        template "app/models/concerns/optimized_finders.rb.tt", "app/models/concerns/optimized_finders.rb"
+        template "app/models/concerns/transitionable.rb.tt", "app/models/concerns/transitionable.rb"
+        template "app/models/concerns/configurable.rb.tt", "app/models/concerns/configurable.rb"
+        template "app/models/configuration.rb.tt", "app/models/configuration.rb"
+      end
+
+      def create_migrations
+        unless migration_exists?("add_status_transitions")
+          template "db/migrate/add_status_transitions.rb.tt",
+                   "db/migrate/#{next_migration_timestamp}_add_status_transitions.rb"
+        end
+        return if migration_exists?("create_configurations")
+
+        template "db/migrate/create_configurations.rb.tt",
+                 "db/migrate/#{next_migration_timestamp}_create_configurations.rb"
+      end
+
+      def create_concern_specs
+        template "spec/models/concerns/searchable_concern_spec.rb.tt", "spec/models/concerns/searchable_concern_spec.rb"
+        template "spec/models/concerns/optimized_finders_spec.rb.tt", "spec/models/concerns/optimized_finders_spec.rb"
+        template "spec/models/concerns/transitionable_spec.rb.tt", "spec/models/concerns/transitionable_spec.rb"
+        template "spec/models/concerns/configurable_spec.rb.tt", "spec/models/concerns/configurable_spec.rb"
+        template "spec/models/configuration_spec.rb.tt", "spec/models/configuration_spec.rb"
+      end
+
+      def inject_into_application_record
+        inject_once(
+          into: "app/models/application_record.rb",
+          content: "  extend SearchableConcern\n  include Configurable\n  include OptimizedFinders",
+          after: "primary_abstract_class\n"
+        )
+      end
+    end
+  end
+end

data/lib/generators/develoz/concerns/templates/app/models/concerns/configurable.rb.tt

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# Convenience helpers for models that own polymorphic [[Configuration]] records.
+#
+# ApplicationRecord includes this module, so every model can read and write its
+# scoped configuration without repeating the for_configurable/find_by dance.
+#
+#   client.configuration_value(:features) # => { 'automation' => true }
+#
+# == The `configurable` DSL
+#
+# `configurable` is the single entrypoint for a configuration-backed attribute.
+# Each declaration maps a virtual attribute to its own dedicated Configuration key
+# (named after the attribute); the stored value IS the attribute value.
+#
+# The generated attribute is writable: assignments are buffered and persisted to
+# the key on save, so controllers just mass-assign and never touch Configuration
+# directly. Reads are lazy (the key is only queried when the reader is called).
+#
+#   class ClientPlatform < ApplicationRecord
+#     configurable :highest_format_only, :boolean
+#   end
+#
+#   client_platform.update!(highest_format_only: true)
+#   client_platform.highest_format_only?  # => true
+#
+# The `type` drives the absent-value default (`:hash` => {}, `:array` => []),
+# kept consistent with `:boolean`; pass `default:` only to override it. Use
+# `global_fallback: true` to merge the global Configuration value under the
+# record-scoped one (scoped wins):
+#
+#   configurable :features, :hash, global_fallback: true
+#
+# Assigning `nil` deletes the scoped record. Override `name=` in the model for any
+# casting/normalisation, calling `write_configuration(name, value)` with the result.
+
+module Configurable
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def configurable(name, type = nil, default: nil, global_fallback: false)
+      name = name.to_sym
+      install_configurable_persistence
+
+      define_method(name) { read_configuration(name, type, default, global_fallback) }
+      define_method("#{name}=") { |value| write_configuration(name, cast_configuration(value, type)) }
+      define_method("#{name}?") { ActiveModel::Type::Boolean.new.cast(public_send(name)) == true } if type == :boolean
+    end
+
+    private
+
+    def install_configurable_persistence
+      return if singleton_class.method_defined?(:configurable?)
+
+      define_singleton_method(:configurable?) { true }
+      after_save :persist_configurations
+    end
+  end
+
+  def configuration_for(key)
+    Configuration.for_configurable(self).active.find_by(key:)
+  end
+
+  def configuration_value(key, default: nil)
+    key = key.to_sym
+    if configurations.key?(key)
+      pending = configurations[key]
+      return pending.nil? ? default : pending
+    end
+
+    configuration = configuration_for(key)
+    configuration ? configuration.value : default
+  end
+
+  def update_configuration(key, value)
+    configuration = Configuration.for_configurable(self).find_or_initialize_by(key:)
+    configuration.update!(value:, active: true)
+    configuration
+  end
+
+  def delete_configuration(key)
+    Configuration.for_configurable(self).where(key:).destroy_all
+  end
+
+  def write_configuration(key, value)
+    configurations[key.to_sym] = value
+  end
+
+  private
+
+  def configurations
+    @configurations ||= {}
+  end
+
+  def cast_configuration(value, type)
+    type == :boolean ? ActiveModel::Type::Boolean.new.cast(value) : value
+  end
+
+  def configurable_default_for(type)
+    case type
+    when :hash then {}
+    when :array then []
+    end
+  end
+
+  def read_configuration(key, type, default, global_fallback)
+    default = configurable_default_for(type) if default.nil?
+    scoped = configuration_value(key, default:)
+    return scoped unless global_fallback
+
+    (Configuration.global_value(key) || {}).merge(scoped || {})
+  end
+
+  def persist_configurations
+    configurations.each do |key, value|
+      value.nil? ? delete_configuration(key) : update_configuration(key, value)
+    end
+    configurations.clear
+  end
+end

data/lib/generators/develoz/concerns/templates/app/models/concerns/optimized_finders.rb.tt

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# OptimizedFinders provides generic find_for and for methods that optimize queries
+# when associations are already loaded or when searching by non-database fields.
+#
+# Usage:
+#   # Find a single record
+#   audit.prices.find_for(variant: 'hd', license: 'buy')
+#
+#   # Find multiple records
+#   audit.prices.for(variant: 'hd', license: 'buy')
+#
+# Optimization logic:
+#   - If called on a loaded association, uses Ruby enumerable methods (no SQL)
+#   - If any search field is not a database column, uses Ruby enumerable methods
+#   - Otherwise, uses database queries (find_by/where)
+module OptimizedFinders
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def find_for(**attributes)
+      find_by(attributes)
+    end
+
+    def for(**attributes)
+      where(attributes)
+    end
+
+    def not_for(**attributes)
+      where.not(attributes)
+    end
+
+    def gather(*attributes)
+      pluck(*attributes)
+    end
+  end
+
+  # Module to prepend to ActiveRecord::Associations::CollectionProxy
+  # This provides optimized implementations for loaded associations
+  module CollectionProxyOptimizations
+    def find_for(**attributes)
+      return super unless should_use_memory_search?(attributes)
+
+      to_a.find { |record| match_attributes?(record, attributes) }
+    end
+
+    def for(**attributes)
+      return super unless should_use_memory_search?(attributes)
+
+      to_a.select { |record| match_attributes?(record, attributes) }
+    end
+
+    def not_for(**attributes)
+      return super unless should_use_memory_search?(attributes)
+
+      to_a.reject { |record| match_attributes?(record, attributes) }
+    end
+
+    def gather(*attributes)
+      return pluck(*attributes) unless should_use_memory_search?(attributes)
+      return to_a.map(&attributes.first) if attributes.size == 1
+
+      to_a.map { |record| read_attributes(record, attributes) }
+    end
+
+    private
+
+    def match_attributes?(record, attributes)
+      attributes.all? do |key, value|
+        record_value = record.public_send(key)
+        value.is_a?(Array) ? value.include?(record_value) : record_value == value
+      end
+    end
+
+    def read_attributes(record, attributes)
+      attributes.map { |attribute| record.public_send(attribute) }
+    end
+
+    # Determines if we should search in memory vs database
+    # Returns true if:
+    #   - Association is already loaded, OR
+    #   - Any search attribute is not a database column (computed/virtual attribute)
+    def should_use_memory_search?(attributes)
+      return true if loaded?
+
+      keys = attributes.is_a?(Hash) ? attributes.keys : attributes
+      keys.any? { |key| klass.column_names.exclude?(key.to_s) }
+    end
+  end
+end
+
+# Prepend optimizations to CollectionProxy so they take precedence
+ActiveRecord::Associations::CollectionProxy.prepend(OptimizedFinders::CollectionProxyOptimizations)

data/lib/generators/develoz/concerns/templates/app/models/concerns/searchable_concern.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Provides full-text search functionality using pg_search gem.
+#
+# ApplicationRecord extends this module, so every model gets `searchable_by`
+# as a class method without any extra mixin overhead. PgSearch::Model is only
+# mixed into a model the first time it calls `searchable_by`.
+#
+# Example:
+#   class Entry < ApplicationRecord
+#     searchable_by %i[first_name last_name email], using: {
+#       trigram: { word_similarity: true }
+#     }
+#   end
+#
+#   Entry.search('john')
+
+module SearchableConcern
+  def searchable_by(*columns, **options)
+    include PgSearch::Model unless include?(PgSearch::Model)
+
+    default_options = {
+      against: columns,
+      using: { tsearch: { prefix: true } }
+    }
+
+    pg_search_scope :search_by_text, default_options.deep_merge(options)
+
+    scope :search, ->(query) { query.present? ? search_by_text(query).reorder(nil) : self }
+  end
+end

data/lib/generators/develoz/concerns/templates/app/models/concerns/transitionable.rb.tt

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# State transition tracking on top of a Rails enum + jsonb log. Replaces
+# statesman for models that have:
+#
+#   - a `status` enum column (string)
+#   - a `status_transitions` jsonb column (default: `[]`)
+#
+# Each entry in `status_transitions` is `{ "to_state" => "...", "created_at" => "<ISO8601>" }`
+# (chronological, append-only). When `transition_metadata` is set before save,
+# it's stored on the new entry under `metadata`.
+#
+# Strict mode (state machine — only declared transitions allowed):
+#
+#   class Order < ApplicationRecord
+#     states pending: %i[paid cancelled],
+#            paid:    %i[shipped refunded],
+#            shipped: [],
+#            cancelled: [],
+#            refunded: []
+#   end
+#
+# Free mode (any-to-any):
+#
+#   class Article < ApplicationRecord
+#     states %i[draft review published archived]
+#   end
+#
+# `states(...)` declares:
+#
+#   - `enum :status, { ... }, default: <first>, suffix: <true|false>` — drive
+#     transitions via the standard Rails enum bang setters (`<state>!` /
+#     `<state>_status!`); the concern hooks status changes via validation
+#     and a before_save callback so `update`/`save`/manual `status =` all work
+#   - a `Klass.transitions` class method returning the transition map
+#     (or `nil` in free mode)
+#   - dynamic `can_be_<state>?` predicates (one per declared state)
+#   - an `in_state(*states)` scope
+#
+# Transition history is recorded automatically on save when `status` changed.
+# To attach metadata to a transition, set `transition_metadata` (an
+# attr_accessor cleared after each save):
+#
+#   page.update!(status: 'analysing_error', transition_metadata: { error: msg })
+#
+# Disallowed transitions surface as a regular validation error on `:status`,
+# so `update!` / `<state>!` raise `ActiveRecord::RecordInvalid`.
+module Transitionable
+  StateTransition = Struct.new(:to_state, :metadata, :created_at, keyword_init: true)
+
+  def states(*positional, suffix: true, **kwargs)
+    states_list, transitions_map = parse_states(positional, kwargs)
+
+    enum(:status, states_list.index_with(&:to_s), default: states_list.first, suffix:)
+    define_singleton_method(:transitions) { transitions_map }
+
+    scope :in_state, ->(*values) { where(status: values.flatten.map(&:to_s)) }
+
+    include Transitionable::Methods
+
+    states_list.each do |state|
+      define_method("can_be_#{state}?") { transition_allowed?(state) }
+    end
+  end
+
+  private
+
+  def parse_states(positional, kwargs)
+    if kwargs.any?
+      raise ArgumentError, "states accepts either a transitions hash or a list of states, not both" if positional.any?
+
+      transitions_map = freeze_transitions(kwargs)
+      [ transitions_map.keys.map(&:to_s), transitions_map ]
+    elsif positional.length == 1 && positional.first.is_a?(Hash)
+      transitions_map = freeze_transitions(positional.first)
+      [ transitions_map.keys.map(&:to_s), transitions_map ]
+    else
+      list = positional.flatten.map(&:to_s).freeze
+      raise ArgumentError, "states requires at least one state" if list.empty?
+
+      [ list, nil ]
+    end
+  end
+
+  def freeze_transitions(hash)
+    hash.transform_keys(&:to_sym)
+        .transform_values { |targets| Array(targets).map(&:to_sym).freeze }
+        .freeze
+  end
+
+  module Methods
+    extend ActiveSupport::Concern
+
+    included do
+      attr_accessor :transition_metadata
+
+      validate :validate_status_transition, if: :status_changed?, on: :update
+      before_update :record_status_transition, if: :status_changed?
+      before_create :record_status_transition, unless: -> { status.blank? || status_transitions.present? }
+    end
+
+    def last_transition
+      return if status_transitions.blank?
+
+      record = status_transitions.last
+      Transitionable::StateTransition.new(
+        to_state: record["to_state"],
+        metadata: record["metadata"] || {},
+        created_at: record["created_at"]
+      )
+    end
+
+    def status_times
+      status_transitions.each_with_object([]) do |entry, acc|
+        time = Time.zone.parse(entry["created_at"].to_s)
+        previous_time = acc.last&.[](:time) || created_at
+        acc << { status: entry["to_state"], previous_time:, time:, duration: time - previous_time }
+      end
+    end
+
+    private
+
+    def transition_allowed?(target)
+      transitions = self.class.transitions
+      return true if transitions.nil?
+
+      from = (status_changed? ? status_was : status)&.to_sym
+      transitions[from]&.include?(target.to_sym) || false
+    end
+
+    def validate_status_transition
+      return if transition_allowed?(status)
+
+      errors.add(:status, "cannot transition from #{status_was.inspect} to #{status.inspect}")
+    end
+
+    def record_status_transition
+      record = { "to_state" => status.to_s, "created_at" => Time.current.iso8601(6) }
+      record["metadata"] = transition_metadata.to_h.deep_stringify_keys if transition_metadata.present?
+      self.status_transitions = Array(status_transitions) + [ record ]
+      self.transition_metadata = nil
+    end
+  end
+end

data/lib/generators/develoz/concerns/templates/app/models/configuration.rb.tt

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: configurations
+#
+#  id                :uuid             not null, primary key
+#  active            :boolean          default(TRUE), not null
+#  configurable_type :string
+#  key               :string           not null
+#  value             :jsonb            not null
+#  created_at        :datetime         not null
+#  updated_at        :datetime         not null
+#  configurable_id   :string
+#
+# Indexes
+#
+#  idx_on_key_configurable_type_configurable_id_4dc9784d18        (key,configurable_type,configurable_id) UNIQUE
+#  index_configurations_on_configurable_id                        (configurable_id)
+#  index_configurations_on_configurable_type_and_configurable_id  (configurable_type,configurable_id)
+#  index_configurations_on_key                                    (key)
+#
+class Configuration < ApplicationRecord
+  CONFIGURABLES = %w[ User Client Platform ClientPlatform ].freeze
+  FORM_CONFIGURABLES = %w[ User Client Platform ].freeze
+
+  attribute :yaml_value, :string
+
+  validates :key, presence: true
+  validates :key, uniqueness: { scope: %i[ configurable_type configurable_id ] }
+  validate :yaml_value_must_parse
+
+  scope :active, -> { where(active: true) }
+  scope :globals, -> { where(configurable_type: nil, configurable_id: nil) }
+  scope :individuals, -> { where("configurable_type IS NOT NULL AND configurable_id IS NOT NULL") }
+  scope :for_configurable, lambda { |configurable|
+    if configurable.is_a?(Hash)
+      configurable_type, configurable_id = configurable.values_at(:type, :id)
+    else
+      configurable_type = configurable&.class&.name
+      configurable_id = configurable&.id
+    end
+
+    where(configurable_type: configurable_type, configurable_id: configurable_id&.to_s)
+  }
+  scope :all_for, ->(configurable) { for_configurable(configurable).or(globals) }
+
+  normalizes :configurable_type, :configurable_id, with: ->(attribute) { attribute.presence&.to_s }
+
+  def self.global_value(path)
+    key, *nested = path.to_s.split(".")
+    value = globals.active.find_by(key: key)&.value
+    nested.inject(value) { |acc, segment| acc.is_a?(Hash) ? acc.with_indifferent_access[segment] : nil }
+  end
+
+  def self.feature_enabled?(path)
+    ActiveModel::Type::Boolean.new.cast(global_value(path)) == true
+  end
+
+  def json_value=(value)
+    self.value = JSON.parse(value) if value.present?
+  end
+
+  def json_value
+    return if value.nil?
+
+    JSON.pretty_generate(value, array_nl: "", indent: "", object_nl: "\n  ")
+  end
+
+  def yaml_value=(input)
+    super
+    self.value = YAML.safe_load(input) if input.present?
+  rescue Psych::SyntaxError
+    # Invalid YAML is kept as raw input and reported by yaml_value_must_parse.
+  end
+
+  def yaml_value
+    read_attribute(:yaml_value).presence || value_as_yaml
+  end
+
+  def configurable_display_name
+    return nil if configurable_id.blank?
+    return configurable_id if CONFIGURABLES.exclude?(configurable_type)
+
+    configurable_type.constantize.find_by(id: configurable_id)&.display_name || configurable_id
+  end
+
+  private
+
+  def value_as_yaml
+    return if value.nil?
+
+    value.to_yaml(line_width: -1).sub(/\A---\s*/, "")
+  end
+
+  def yaml_value_must_parse
+    raw_yaml = self[:yaml_value]
+    return if raw_yaml.blank?
+
+    YAML.safe_load(raw_yaml)
+  rescue Psych::SyntaxError => e
+    errors.add(:yaml_value, "is not valid YAML: #{e.message}")
+  end
+end

data/lib/generators/develoz/concerns/templates/db/migrate/add_status_transitions.rb.tt

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Adds the columns required by the Transitionable concern to a model.
+# Copy this migration and replace `:records` with your model's table name.
+class AddStatusTransitions < ActiveRecord::Migration[8.0]
+  disable_ddl_transaction!
+
+  def up
+    return unless table_exists?(:records)
+
+    unless column_exists?(:records, :status)
+      add_column :records, :status, :string, default: "pending", null: false
+    end
+
+    unless column_exists?(:records, :status_transitions)
+      add_column :records, :status_transitions, :jsonb, default: [], null: false
+    end
+
+    return if index_exists?(:records, :status)
+
+    add_index :records, :status, algorithm: :concurrently
+  end
+
+  def down
+    return unless table_exists?(:records)
+    remove_index :records, :status if index_exists?(:records, :status)
+    remove_column :records, :status_transitions if column_exists?(:records, :status_transitions)
+    remove_column :records, :status if column_exists?(:records, :status)
+  end
+end

data/lib/generators/develoz/concerns/templates/db/migrate/create_configurations.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Creates the polymorphic configurations table used by the Configurable concern.
+# Requires the pgcrypto extension for UUID generation.
+class CreateConfigurations < ActiveRecord::Migration[8.0]
+  disable_ddl_transaction!
+
+  def change
+    enable_extension "pgcrypto" unless extension_enabled?("pgcrypto")
+    enable_extension "uuid-ossp" unless extension_enabled?("uuid-ossp")
+
+    create_table :configurations, id: :uuid, default: "public.uuid_generate_v1()" do |t|
+      t.string :key, null: false, index: true
+      t.jsonb :value, null: false, default: {}
+      t.string :configurable_type
+      t.string :configurable_id
+      t.boolean :active, default: true, null: false
+
+      t.timestamps
+    end
+
+    add_index :configurations, %i[configurable_type configurable_id], algorithm: :concurrently
+    add_index :configurations, %i[key configurable_type configurable_id], unique: true, algorithm: :concurrently
+  end
+end