athar 0.1.0

data/lib/generators/athar/install/install_generator.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require "athar/sql"
+require_relative "../fx_helper"
+
+module Athar
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+      include FxHelper
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :update,
+                   type: :boolean,
+                   default: false,
+                   desc: "Generate a function-only migration that updates Athar SQL functions."
+
+      def validate_options!
+        ensure_raw_sql_supported! unless fx?
+      end
+
+      def write_function_files
+        return unless fx?
+
+        FileUtils.mkdir_p(functions_destination)
+        function_definitions.each do |function_definition|
+          path = File.join(functions_destination, "#{function_definition[:versioned_basename]}.sql")
+          next if File.exist?(path) && File.read(path) == function_definition[:body]
+
+          File.write(path, function_definition[:body])
+        end
+      end
+
+      def generate_migration
+        template = fx? ? "install_migration_fx.rb.erb" : "install_migration.rb.erb"
+        migration_template template, "db/migrate/#{migration_filename}.rb"
+      end
+
+      no_tasks do # rubocop:disable Metrics/BlockLength
+        def migration_filename
+          if options[:update]
+            version = function_definitions.map { |definition| definition[:version] }.max
+            "athar_update_functions_v#{version.to_s.rjust(2, "0")}"
+          else
+            "athar_install"
+          end
+        end
+
+        def function_definitions # rubocop:disable Metrics/MethodLength
+          @function_definitions ||= Athar::SQL::INSTALLED_FUNCTIONS.map do |name|
+            previous_version = previous_version_for(name)
+            new_body = Athar::SQL.read_function(name, foreign_key_type:)
+
+            version = if previous_version
+                        previous_body = read_existing_function(name, previous_version)
+                        previous_body == new_body ? previous_version : previous_version + 1
+                      else
+                        1
+                      end
+
+            {
+              name:,
+              version:,
+              previous_version:,
+              versioned_basename: "#{name}_v#{version.to_s.rjust(2, "0")}",
+              body: new_body,
+              signature: Athar::SQL.function_signature(name)
+            }
+          end
+        end
+
+        def previous_version_for(name)
+          return nil unless File.directory?(functions_destination)
+
+          Dir.entries(functions_destination)
+             .filter_map { |path| path[/\A#{Regexp.escape(name)}_v(\d+)\.sql\z/, 1]&.to_i }
+             .max
+        end
+
+        def functions_destination
+          File.expand_path("db/functions", destination_root)
+        end
+
+        def read_existing_function(name, version)
+          path = File.join(functions_destination, "#{name}_v#{version.to_s.rjust(2, "0")}.sql")
+          File.exist?(path) ? File.read(path) : nil
+        end
+
+        def function_drops
+          Athar::SQL::INSTALLED_FUNCTIONS.map do |name|
+            "DROP FUNCTION IF EXISTS #{name}(#{Athar::SQL.function_signature(name)}) CASCADE;"
+          end
+        end
+
+        def migration_class_name
+          migration_filename.camelize
+        end
+
+        def foreign_key_type
+          athar_foreign_key_type
+        end
+
+        def update?
+          options[:update]
+        end
+      end
+
+      def self.next_migration_number(dir)
+        ::ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+    end
+  end
+end

data/lib/generators/athar/install/templates/install_migration.rb.erb

@@ -0,0 +1,80 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+<% unless update? -%>
+    primary_key_type, foreign_key_type = athar_primary_and_foreign_key_types
+
+    create_table :athar_deletions, id: primary_key_type do |t|
+      t.references :record,
+        polymorphic: true,
+        null: false,
+        type: foreign_key_type,
+        index: {name: "index_athar_deletions_on_record"}
+
+      t.references :actor,
+        polymorphic: true,
+        type: foreign_key_type,
+        index: {name: "index_athar_deletions_on_actor"}
+
+      t.string :schema_name
+      t.string :table_name, null: false
+      t.datetime :deleted_at, null: false
+      t.datetime :created_at, null: false
+
+      t.jsonb :record_data, null: false, default: {}
+      t.jsonb :metadata, null: false, default: {}
+    end
+
+    add_index :athar_deletions, [:deleted_at, :id]
+    add_index :athar_deletions, [:table_name, :deleted_at]
+    add_index :athar_deletions, [:schema_name, :table_name, :record_id],
+      name: "index_athar_deletions_on_record_lookup"
+
+    create_table :athar_table_events, id: primary_key_type do |t|
+      t.string :event_type, null: false
+      t.string :schema_name
+      t.string :table_name, null: false
+      t.references :actor,
+        polymorphic: true,
+        type: foreign_key_type,
+        index: {name: "index_athar_table_events_on_actor"}
+      t.jsonb :metadata, null: false, default: {}
+      t.datetime :occurred_at, null: false
+      t.datetime :created_at, null: false
+    end
+
+    add_index :athar_table_events, [:event_type, :table_name, :occurred_at],
+      name: "index_athar_table_events_on_type_table_time"
+    add_index :athar_table_events, :occurred_at
+<% end -%>
+
+    execute(<<~SQL)
+<% function_definitions.each do |function_definition| -%>
+<%= indent_sql(function_definition[:body], 6) %>
+<% end -%>
+    SQL
+  end
+
+  def down
+<% unless update? -%>
+    drop_table :athar_table_events if table_exists?(:athar_table_events)
+    drop_table :athar_deletions if table_exists?(:athar_deletions)
+<% end -%>
+
+    execute(<<~SQL)
+<% function_drops.each do |drop_sql| -%>
+      <%= drop_sql %>
+<% end -%>
+    SQL
+  end
+
+  private
+
+  def athar_primary_and_foreign_key_types
+    generators_config = Rails.configuration.generators
+    orm = generators_config.orm
+    setting = generators_config.options[orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [primary_key_type, foreign_key_type]
+  end
+end

data/lib/generators/athar/install/templates/install_migration_fx.rb.erb

@@ -0,0 +1,73 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+<% unless update? -%>
+    primary_key_type, foreign_key_type = athar_primary_and_foreign_key_types
+
+    create_table :athar_deletions, id: primary_key_type do |t|
+      t.references :record,
+        polymorphic: true,
+        null: false,
+        type: foreign_key_type,
+        index: {name: "index_athar_deletions_on_record"}
+
+      t.references :actor,
+        polymorphic: true,
+        type: foreign_key_type,
+        index: {name: "index_athar_deletions_on_actor"}
+
+      t.string :schema_name
+      t.string :table_name, null: false
+      t.datetime :deleted_at, null: false
+      t.datetime :created_at, null: false
+
+      t.jsonb :record_data, null: false, default: {}
+      t.jsonb :metadata, null: false, default: {}
+    end
+
+    add_index :athar_deletions, [:deleted_at, :id]
+    add_index :athar_deletions, [:table_name, :deleted_at]
+    add_index :athar_deletions, [:schema_name, :table_name, :record_id],
+      name: "index_athar_deletions_on_record_lookup"
+
+    create_table :athar_table_events, id: primary_key_type do |t|
+      t.string :event_type, null: false
+      t.string :schema_name
+      t.string :table_name, null: false
+      t.references :actor,
+        polymorphic: true,
+        type: foreign_key_type,
+        index: {name: "index_athar_table_events_on_actor"}
+      t.jsonb :metadata, null: false, default: {}
+      t.datetime :occurred_at, null: false
+      t.datetime :created_at, null: false
+    end
+
+    add_index :athar_table_events, [:event_type, :table_name, :occurred_at],
+      name: "index_athar_table_events_on_type_table_time"
+    add_index :athar_table_events, :occurred_at
+<% end -%>
+
+<% function_definitions.each do |function_definition| -%>
+<% if function_definition[:previous_version].nil? -%>
+    create_function :<%= function_definition[:name] %>, version: <%= function_definition[:version] %>
+<% elsif function_definition[:previous_version] == function_definition[:version] -%>
+    # <%= function_definition[:name] %> is already at version <%= function_definition[:version] %>; nothing to do.
+<% else -%>
+    update_function :<%= function_definition[:name] %>,
+      version: <%= function_definition[:version] %>,
+      revert_to_version: <%= function_definition[:previous_version] %>
+<% end -%>
+<% end -%>
+  end
+
+  private
+
+  def athar_primary_and_foreign_key_types
+    generators_config = Rails.configuration.generators
+    orm = generators_config.orm
+    setting = generators_config.options[orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [primary_key_type, foreign_key_type]
+  end
+end

data/lib/generators/athar/model/model_generator.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require "athar/sql"
+require_relative "../fx_helper"
+
+module Athar
+  module Generators
+    class ModelGenerator < ::Rails::Generators::NamedBase # rubocop:disable Metrics/ClassLength
+      include ::Rails::Generators::Migration
+      include FxHelper
+
+      ALLOWED_ID_TYPES = %w[bigint integer uuid].freeze
+      CAPTURE_MODES = %w[identity only snapshot].freeze
+      UNSAFE_COLUMN_REGEX = /[\s,{}"\\']/
+      # PostgreSQL unquoted identifier surface: starts with letter or _,
+      # then letters/digits/underscores. Matches what the generator embeds
+      # inside both `"identifier"` and `'string'` SQL contexts.
+      SAFE_IDENTIFIER_REGEX = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+      # Ruby class names, with optional `::` namespacing.
+      SAFE_CLASS_NAME_REGEX = /\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*\z/
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :name, type: :string, banner: "ModelName"
+
+      class_option :only, type: :array, default: nil, desc: "Capture only the listed columns. Comma-separated."
+      class_option :snapshot, type: :boolean, default: false, desc: "Capture all row attributes."
+      class_option :primary_key, type: :string, default: nil, desc: "Primary key column."
+      class_option :record_type, type: :string, default: nil, desc: "Override the stored record_type."
+      class_option :record_type_column, type: :string, default: nil, desc: "STI column. Pass 'false' to disable."
+      class_option :schema, type: :string, default: nil, desc: "PostgreSQL schema."
+      class_option :track_truncate, type: :boolean, default: false, desc: "Install AFTER TRUNCATE trigger."
+      class_option :update, type: :boolean, default: false, desc: "Generate an update migration."
+      class_option :remove, type: :boolean, default: false, desc: "Generate a removal migration."
+
+      def validate_options!
+        validate_capture_mode!
+        validate_identifiers!
+        validate_id_type!
+        validate_columns!
+        ensure_raw_sql_supported! unless fx?
+      end
+
+      def write_trigger_files # rubocop:disable Metrics/AbcSize
+        return unless fx?
+        return if remove?
+
+        FileUtils.mkdir_p(triggers_destination)
+        # Reading trigger_descriptors first caches the version computation
+        # against the on-disk state *before* we write the new files.
+        trigger_descriptors.each do |descriptor|
+          path = File.join(
+            triggers_destination,
+            "#{descriptor[:name]}_v#{descriptor[:version].to_s.rjust(2, "0")}.sql"
+          )
+          next if File.exist?(path) && File.read(path) == descriptor[:body]
+
+          File.write(path, descriptor[:body])
+        end
+      end
+
+      def generate_migration
+        template = fx? ? "migration_fx.rb.erb" : "migration.rb.erb"
+        migration_template template, "db/migrate/#{migration_filename}.rb"
+      end
+
+      no_tasks do # rubocop:disable Metrics/BlockLength
+        def trigger_descriptors
+          @trigger_descriptors ||= begin
+            descriptors = []
+            unless remove?
+              descriptors << build_descriptor(trigger_name, render_trigger("athar_delete"))
+              if track_truncate?
+                descriptors << build_descriptor(truncate_trigger_name, render_trigger("athar_truncate"))
+              end
+            end
+            descriptors
+          end
+        end
+
+        def build_descriptor(name, body)
+          version = trigger_version_for(name, body)
+          previous = previous_version_for(name)
+          {
+            name:,
+            body:,
+            version:,
+            previous_version: previous,
+            unchanged: !previous.nil? && version == previous
+          }
+        end
+
+        def trigger_name
+          "athar_on_#{table_name}"
+        end
+
+        def truncate_trigger_name
+          "athar_truncate_on_#{table_name}"
+        end
+
+        def render_trigger(template_name)
+          path = File.join(Athar::SQL::MODEL_TRIGGERS_DIR, "#{template_name}.sql.erb")
+          template = File.read(path)
+          locals = {
+            schema_name:,
+            table_name:,
+            trigger_name:,
+            truncate_trigger_name:,
+            record_type:,
+            primary_key:,
+            id_type:,
+            record_type_column_arg:,
+            capture_mode:,
+            columns_arg:
+          }
+          Athar::SQL.render(template, locals)
+        end
+
+        def trigger_sql
+          render_trigger("athar_delete")
+        end
+
+        def truncate_trigger_sql
+          render_trigger("athar_truncate")
+        end
+
+        def drop_trigger_sql
+          [
+            %(DROP TRIGGER IF EXISTS "#{trigger_name}" ON "#{schema_name}"."#{table_name}";),
+            (track_truncate? ? %(DROP TRIGGER IF EXISTS "#{truncate_trigger_name}" ON "#{schema_name}"."#{table_name}";) : nil) # rubocop:disable Layout/LineLength
+          ].compact.join("\n")
+        end
+
+        def triggers_destination
+          File.expand_path("db/triggers", destination_root)
+        end
+
+        def trigger_version_for(target, body)
+          previous = previous_version_for(target)
+          return 1 if previous.nil?
+
+          previous_path = File.join(triggers_destination, "#{target}_v#{previous.to_s.rjust(2, "0")}.sql")
+          previous_body = File.exist?(previous_path) ? File.read(previous_path) : nil
+          previous_body == body ? previous : previous + 1
+        end
+
+        def previous_version_for(target)
+          return nil unless File.directory?(triggers_destination)
+
+          Dir.entries(triggers_destination)
+             .filter_map { |path| path[/\A#{Regexp.escape(target)}_v(\d+)\.sql\z/, 1]&.to_i }
+             .max
+        end
+
+        def model_class
+          @model_class ||= name.classify.constantize
+        end
+
+        def schema_name
+          options[:schema] || schema_and_table_name.first || "public"
+        end
+
+        def table_name
+          schema_and_table_name.last
+        end
+
+        def schema_and_table_name
+          full = model_class.table_name.to_s
+          @schema_and_table_name ||= full.include?(".") ? full.split(".", 2) : [nil, full]
+        end
+
+        def record_type
+          options[:record_type] || model_class.base_class.name
+        end
+
+        def primary_key
+          options[:primary_key] || model_class.primary_key.to_s
+        end
+
+        def id_type
+          column = model_class.columns_hash[primary_key]
+          raise_invalid("Primary key column #{primary_key.inspect} not found on #{table_name}") unless column
+
+          sql_type = column.sql_type.to_s.downcase
+          case sql_type
+          when "bigint", "int8" then "bigint"
+          when "integer", "int", "int4" then "integer"
+          when "uuid" then "uuid"
+          else
+            raise_invalid("Unsupported primary key SQL type #{sql_type.inspect}; allowed: #{ALLOWED_ID_TYPES.inspect}")
+          end
+        end
+
+        def record_type_column # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          override = options[:record_type_column]
+          if override.nil?
+            inheritance = model_class.inheritance_column
+            inheritance if model_class.columns_hash.key?(inheritance.to_s)
+          elsif override.to_s == "false"
+            nil
+          else
+            unless model_class.columns_hash.key?(override.to_s)
+              raise_invalid("Record type column #{override.inspect} not found on #{table_name}")
+            end
+            override.to_s
+          end
+        end
+
+        def record_type_column_arg
+          rtc = record_type_column
+          rtc ? "'#{rtc}'" : "'null'"
+        end
+
+        def capture_mode
+          if options[:snapshot]
+            "snapshot"
+          elsif options[:only]
+            "only"
+          else
+            "identity"
+          end
+        end
+
+        def columns
+          Array(options[:only]).flat_map { |item| item.to_s.split(",") }.map(&:strip).reject(&:empty?)
+        end
+
+        def columns_arg
+          capture_mode == "only" ? "'{#{columns.join(",")}}'" : "'null'"
+        end
+
+        def migration_filename
+          if remove?
+            "athar_remove_#{table_name}_trigger"
+          elsif update?
+            # Fold the new version into the filename so consecutive --update
+            # runs produce distinct files and Ruby constants.
+            version = trigger_descriptors.map { |descriptor| descriptor[:version] }.max
+            "athar_update_#{table_name}_trigger_v#{version.to_s.rjust(2, "0")}"
+          else
+            "athar_install_#{table_name}_trigger"
+          end
+        end
+
+        def migration_class_name
+          migration_filename.camelize
+        end
+
+        # The `on:` argument passed to Fx's create_trigger / update_trigger /
+        # drop_trigger. For the public schema we keep the bare symbol so the
+        # generated migration matches the Rails convention. For non-public
+        # schemas we pass a "schema.table" string so DROP TRIGGER … ON … hits
+        # the correct relation regardless of search_path.
+        def fx_on_argument
+          if schema_name == "public"
+            ":#{table_name}"
+          else
+            %("#{schema_name}.#{table_name}")
+          end
+        end
+
+        def track_truncate?
+          options[:track_truncate]
+        end
+
+        def update?
+          options[:update]
+        end
+
+        def remove?
+          options[:remove]
+        end
+      end
+
+      def self.next_migration_number(dir)
+        ::ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      private
+
+      def validate_capture_mode!
+        return unless options[:only] && options[:snapshot]
+
+        raise_invalid("--only and --snapshot are mutually exclusive")
+      end
+
+      def validate_identifiers!
+        validate_safe_identifier!("schema", schema_name)
+        return if remove?
+
+        validate_safe_identifier!("table", table_name)
+        validate_safe_identifier!("primary_key", primary_key)
+        validate_safe_class_name!("record_type", record_type)
+
+        rtc_override = options[:record_type_column]
+        return if rtc_override.nil? || rtc_override.to_s == "false"
+
+        # Validate shape before record_type_column tries to look it up against
+        # the model's columns; otherwise an unsafe value would surface as a
+        # confusing "not found" error.
+        validate_safe_identifier!("record_type_column", rtc_override)
+      end
+
+      def validate_safe_identifier!(label, value)
+        return if value.to_s.match?(SAFE_IDENTIFIER_REGEX)
+
+        raise_invalid("#{label} #{value.inspect} is not a safe SQL identifier; allowed: #{SAFE_IDENTIFIER_REGEX.source}") # rubocop:disable Layout/LineLength
+      end
+
+      def validate_safe_class_name!(label, value)
+        return if value.to_s.match?(SAFE_CLASS_NAME_REGEX)
+
+        raise_invalid("#{label} #{value.inspect} is not a safe Ruby class name")
+      end
+
+      def validate_id_type!
+        return if remove?
+        return if ALLOWED_ID_TYPES.include?(id_type)
+
+        raise_invalid("id type must be one of #{ALLOWED_ID_TYPES.inspect}, got #{id_type.inspect}")
+      end
+
+      def validate_columns!
+        return unless options[:only]
+
+        columns.each do |column|
+          if column.match?(UNSAFE_COLUMN_REGEX)
+            raise_invalid("column name #{column.inspect} contains unsafe characters")
+          end
+
+          unless model_class.columns_hash.key?(column)
+            raise_invalid("column #{column.inspect} not found on #{table_name}")
+          end
+        end
+      end
+
+      def raise_invalid(message)
+        raise ::Thor::Error, "Athar generator error: #{message}"
+      end
+    end
+  end
+end

data/lib/generators/athar/model/templates/migration.rb.erb

@@ -0,0 +1,47 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+<% if remove? -%>
+  def up
+    execute(<<~SQL)
+<%= indent_sql(drop_trigger_sql, 6) %>
+    SQL
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+<% elsif update? -%>
+  def up
+    execute(<<~SQL)
+<%= indent_sql(drop_trigger_sql, 6) %>
+
+<%= indent_sql(trigger_sql, 6) %>
+<% if track_truncate? -%>
+
+<%= indent_sql(truncate_trigger_sql, 6) %>
+<% end -%>
+    SQL
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+<% else -%>
+  def up
+    execute(<<~SQL)
+<%= indent_sql(drop_trigger_sql, 6) %>
+
+<%= indent_sql(trigger_sql, 6) %>
+<% if track_truncate? -%>
+
+<%= indent_sql(truncate_trigger_sql, 6) %>
+<% end -%>
+    SQL
+  end
+
+  def down
+    execute(<<~SQL)
+<%= indent_sql(drop_trigger_sql, 6) %>
+    SQL
+  end
+<% end -%>
+end

data/lib/generators/athar/model/templates/migration_fx.rb.erb

@@ -0,0 +1,29 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+<% if remove? -%>
+  def up
+    drop_trigger :<%= trigger_name %>, on: <%= fx_on_argument %>
+<% if track_truncate? -%>
+    drop_trigger :<%= truncate_trigger_name %>, on: <%= fx_on_argument %>
+<% end -%>
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+<% else -%>
+  def change
+<% trigger_descriptors.each do |t| -%>
+<% if t[:previous_version].nil? -%>
+    create_trigger :<%= t[:name] %>, on: <%= fx_on_argument %>, version: <%= t[:version] %>
+<% elsif t[:unchanged] -%>
+    # <%= t[:name] %> is already at version <%= t[:version] %>; nothing to do.
+<% else -%>
+    update_trigger :<%= t[:name] %>,
+      on: <%= fx_on_argument %>,
+      version: <%= t[:version] %>,
+      revert_to_version: <%= t[:previous_version] %>
+<% end -%>
+<% end -%>
+  end
+<% end -%>
+end