historiographer 4.1.13 → 4.1.16

data/instructions/implementation.md

@@ -0,0 +1,282 @@
+# Single Table Inheritance (STI) Implementation for Historiographer
+
+You are assisting with a Rails gem called Historiographer. Your role is to make precise, surgical edits to the codebase based on specific tasks. The project has a complex architecture with interdependent components, so caution is required.
+
+## Overview
+
+This document outlines the steps needed to properly implement Single Table Inheritance (STI) for the Historiographer gem, following Rails best practices. The current implementation has a complex method forwarding mechanism that can lead to subtle bugs. We need to refactor this to use a clean, standard Rails STI approach within separate inheritance hierarchies.
+
+## Current State Analysis
+
+The current implementation has the following issues:
+
+1. History classes implement a complex method delegation approach using `method_missing` and dynamic method definition
+2. STI is partially implemented but doesn't correctly handle the inheritance hierarchy within history classes
+3. The `type` column isn't properly set or managed according to Rails STI conventions
+4. Method delegation between original and history models is overly complex and error-prone
+
+## Implementation Requirements
+
+1. User can define a `type` for their class, and that will be used to identify the STI class
+2. The `type` should be a string, and the default value should be the class name
+3. When a user creates a new instance, the `type` should be set to the class name automatically
+4. STI subclasses should automatically inherit from their parent class
+5. History classes should maintain a parallel inheritance hierarchy to original classes
+6. When finding a history instance, it should automatically instantiate the correct subclass based on `type`
+7. Implement clean method delegation from history classes to original models
+
+## Implementation Approach: STI Within History Models
+
+We will implement STI separately within original models and history models, maintaining two parallel inheritance hierarchies:
+
+1. **Original Models Hierarchy**: `PrivatePost < Post < ActiveRecord::Base`
+2. **History Models Hierarchy**: `PrivatePostHistory < PostHistory < ActiveRecord::Base`
+
+This approach follows Rails conventions within each table while providing a clean way to implement method delegation between related models.
+
+## Implementation Steps
+
+### 1. Update `Historiographer::History` Module
+
+#### Changes Required:
+
+- Implement a clean method delegation system using `method_missing`
+- Support proper STI inheritance within history models
+- Ensure history classes correctly set and manage their `type` column
+- Maintain table separation between original and history models
+
+```ruby
+module Historiographer
+  module History
+    extend ActiveSupport::Concern
+
+    included do |base|
+      clear_validators! if respond_to?(:clear_validators!)
+
+      # Current scope for finding the most recent history
+      scope :current, -> { where(history_ended_at: nil).order(id: :desc) }
+
+      # Determine original class name
+      cattr_accessor :original_class_name
+      self.original_class_name = base.name.gsub(/History$/, '')
+
+      # Setup inheritance column for history classes
+      if self.original_class_name.constantize.respond_to?(:inheritance_column)
+        original_inheritance_column = self.original_class_name.constantize.inheritance_column
+        self.inheritance_column = original_inheritance_column
+      end
+
+      # Set up user association
+      unless self.original_class_name.constantize.ancestors.include?(Historiographer::Silent)
+        belongs_to :user, foreign_key: :history_user_id
+      end
+
+      # Ensure we can't destroy history records
+      before_destroy { |record| raise "Cannot destroy history records" }
+
+      # Handle type column for history classes
+      after_initialize do
+        # Set type to the history class if not already set
+        if self.type.nil? || !self.type.ends_with?('History')
+          self.type = self.class.name
+        end
+      end
+
+      # Setup class accessors for delegation
+      cattr_accessor :delegated_methods
+      self.delegated_methods = []
+    end
+
+    # Method delegation system
+    def method_missing(method, *args, &block)
+      # Try to find the original record to delegate to
+      foreign_key = self.class.determine_foreign_key
+      original_record = self.class.original_class_name.constantize.find_by(id: send(foreign_key))
+
+      if original_record && original_record.respond_to?(method)
+        # Cache the method for future calls
+        self.class.delegate_method(method)
+        # Call the method on the original record
+        original_record.send(method, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      # Check if the original class responds to this method
+      foreign_key = self.class.determine_foreign_key
+      original_record = self.class.original_class_name.constantize.find_by(id: send(foreign_key))
+      original_record&.respond_to?(method, include_private) || super
+    end
+
+    class_methods do
+      # Method to delegate methods from original class
+      def delegate_method(method_name)
+        return if method_defined?(method_name) || delegated_methods.include?(method_name.to_sym)
+
+        delegated_methods << method_name.to_sym
+
+        define_method(method_name) do |*args, &block|
+          foreign_key = self.class.determine_foreign_key
+          original_record = self.class.original_class_name.constantize.find_by(id: send(foreign_key))
+
+          if original_record
+            original_record.send(method_name, *args, &block)
+          else
+            raise NoMethodError, "undefined method `#{method_name}' for #{self}"
+          end
+        end
+      end
+
+      # Determine the foreign key based on the original class
+      def determine_foreign_key
+        association_name = self.original_class_name.split("::").last.underscore
+        "#{association_name}_id"
+      end
+    end
+
+    # Prevent destroying history records
+    def destroy
+      false
+    end
+
+    def destroy!
+      false
+    end
+
+    # Other existing scopes and methods...
+  end
+end
+```
+
+### 2. Update Original Model STI Support in `Historiographer` Module
+
+#### Changes Required:
+
+- Ensure proper type column handling in original models
+- Support proper mapping between original and history class hierarchy
+- Handle custom inheritance columns
+
+```ruby
+module Historiographer
+  extend ActiveSupport::Concern
+
+  included do |base|
+    # Existing code...
+
+    # Set default type for original models
+    if base.respond_to?(:inheritance_column) && base.column_names.include?(base.inheritance_column)
+      before_validation do
+        self[self.class.inheritance_column] ||= self.class.name
+      end
+    end
+
+    # Ensure history class creation supports STI
+    class_name = "#{base.name}History"
+
+    begin
+      history_class = class_name.constantize
+    rescue NameError
+      # Get the base table name without _histories suffix
+      base_table = base.table_name.singularize.sub(/_histories$/, '')
+
+      # Find the correct parent history class for STI
+      if base.superclass != ActiveRecord::Base && base.superclass.include?(Historiographer)
+        parent_history_class_name = "#{base.superclass.name}History"
+        begin
+          parent_history_class = parent_history_class_name.constantize
+        rescue NameError
+          parent_history_class = ActiveRecord::Base
+        end
+      else
+        parent_history_class = ActiveRecord::Base
+      end
+
+      # Create history class with proper inheritance
+      history_class_initializer = Class.new(parent_history_class) do
+        self.table_name = "#{base_table}_histories"
+        include Historiographer::History
+
+        # Set original class name for delegation
+        self.original_class_name = base.name
+
+        # Handle inheritance column
+        if base.respond_to?(:inheritance_column)
+          self.inheritance_column = base.inheritance_column
+        end
+      end
+
+      # Register the new class in the proper namespace
+      module_parts = class_name.split('::')
+      final_class_name = module_parts.pop
+
+      # Find or create module nesting
+      parent_module = Object
+      module_parts.each do |part|
+        parent_module = if parent_module.const_defined?(part)
+                        parent_module.const_get(part)
+                      else
+                        parent_module.const_set(part, Module.new)
+                      end
+      end
+
+      # Define the history class
+      history_class = parent_module.const_set(final_class_name, history_class_initializer)
+    end
+
+    # Existing code...
+  end
+
+  # Add helper methods for STI
+  module ClassMethods
+    def history_class_for_type(type_value)
+      if type_value.present?
+        "#{type_value}History".constantize
+      else
+        "#{self.name}History".constantize
+      end
+    rescue NameError
+      history_class
+    end
+  end
+
+  # Instance methods related to history and STI
+  def create_history(snapshot_id: nil)
+    # Use the correct history class based on the current type
+    type_column = self.class.inheritance_column
+    current_type = self[type_column] || self.class.name
+
+    begin
+      specific_history_class = self.class.history_class_for_type(current_type)
+    rescue NameError
+      specific_history_class = self.class.history_class
+    end
+
+    # Create history record with the proper type
+    history_record = record_history(specific_history_class, snapshot_id: snapshot_id)
+    history_record
+  end
+end
+```
+
+## Migration Testing Requirements
+
+1. Create comprehensive test cases for STI behavior in original and history models
+2. Test inheritance between original models (e.g., `PrivatePost < Post`)
+3. Test inheritance between history models (e.g., `PrivatePostHistory < PostHistory`)
+4. Test method delegation from history models to original models
+5. Test custom inheritance columns
+6. Test namespaced models
+7. Verify proper handling of the `type` column in both original and history tables
+
+## Backward Compatibility
+
+To ensure backward compatibility:
+
+1. Maintain existing history table structures
+2. Ensure old history records continue to work with the new implementation
+3. Support the same public API for accessing history records
+4. Handle existing applications that may have customized history class behavior
+
+By implementing STI separately within original and history models, we maintain Rails conventions while providing clean method delegation between related models.

data/instructions/todo.md

@@ -0,0 +1,96 @@
+## Context
+
+You are assisting with a Rails gem called Historiographer. Your role is to make precise, surgical edits to the codebase based on specific tasks. The project has a complex architecture with interdependent components, so caution is required.
+
+## Task:
+
+We are going to PROPERLY implement Single Table Inheritance (STI) for Historiographer, in line with Rails best practices.
+
+There is some existing code in here that implements STI, but it is not done correctly. We need to fix that.
+
+## Requirements:
+
+1. User can define a `type` for their class, and that will be used to identify the STI class
+2. In keeping with STI conventions, the `type` should be a string, and the default value should be the class name
+3. When a user creates a new instance of a class, the `type` should be set to the class name, and the class should automatically inherit the STI class
+
+In historiographer, we use a `histories` table for each model, for example:
+
+datasources => datasource_histories
+
+With STI, it is okay for us to have:
+
+class Datasource < ActiveRecord::Base
+def refresh # implemented in sub-classes
+end
+end
+
+class S3Datasource < Datasource
+def refresh
+s3.refresh
+end
+end
+
+class DatasourceHistory < Datasource
+end
+
+class S3DatasourceHistory < DatasourceHistory
+end
+
+4. But the STI class should automatically inherit the STI class, allowing it to use methods defined on the STI class, meaning that S3DatasourceHistory should have access to the `refresh` method that uses s3
+
+5. When we find an instance of DatasourceHistory, it should automatically give us the S3DatasourceHistory class if the `type` is "S3Datasource"
+
+6. The History classes currently have a VERY tricky and complicated way of doing STI that allows them to both act as proper history classes, and "proxy all requests" to the original class. This causes complicated and subtle bugs, and we need to fix that. I would assume that we should do this by inheriting from the original class, which will handle regular inheritance... but then we maybe need to include Historiographer::History to gain access to the history functionality.
+
+7. Implement tests which verify that the STI is working correctly, and that History objects can properly call all methods on the original class.
+
+## Rules
+
+### Do No Harm
+
+- Do not remove any code that seems to be irrelevant to your task. You do not have full context of the application, so you should err on the side of NOT removing code, unless the code is clearly duplication.
+- Preserve existing formatting, naming conventions, and code style whenever possible.
+- Keep changes minimal and focused on the specific task at hand.
+
+### Before Starting
+
+- Look for any files you might need to understand the context better
+- If you have any questions, DO NOT WRITE CODE. Ask the question. I will be happy to answer all your questions to your satisfaction before you start.
+- Measure twice, cut once!
+- Understand the full impact of your changes before implementing them.
+
+### Working Process
+
+1. **Analyze First**: Carefully review the code before suggesting any changes.
+2. **Ask Questions**: If anything is unclear, ask before proceeding.
+3. **Plan Your Approach**: Outline your intended changes before executing them.
+4. **Make Minimal Changes**: Focus only on what's needed for the task.
+5. **Explain Your Changes**: Document what you've done and why.
+
+## Technology-Specific Guidelines
+
+### Rails
+
+- Be aware of model associations and their dependencies.
+- Don't alter database migrations unless specifically asked.
+- Pay attention to Rails conventions and patterns in the existing code.
+- Be cautious when modifying controllers that might affect multiple views.
+
+## Common Pitfalls to Avoid
+
+- Adding unnecessary abstractions or "improvements" beyond the scope of the task
+- Rewriting functional code in your preferred style when it's not needed
+- Making major architectural changes when only small fixes are required
+- Assuming you understand the full context of the application
+- Using libraries or approaches not already in use in the project
+
+## Communication Guidelines
+
+- Be specific about what you're changing and why
+- If you're uncertain about something, ask first
+- Identify potential risks or side effects of your changes
+- If you spot issues unrelated to your task, note them separately without fixing them
+- Provide clear explanations of your thought process
+
+Remember: Your primary goal is to complete the specific task assigned with minimal disruption to the existing codebase. Quality and precision are more important than clever or extensive changes.

data/lib/historiographer/history.rb

@@ -317,13 +317,7 @@ module Historiographer
 
       def sti_base_class
         return @sti_base_class if @sti_base_class
-
-        base_name = name.gsub(/History$/, '')
-        base_class = base_name.constantize
-        while base_class.superclass != ActiveRecord::Base
-          base_class = base_class.superclass
-        end
-        @sti_base_class = base_class
+        @sti_base_class = original_class.base_class
       end
     end
 

data/lib/historiographer/version.rb

@@ -1,3 +1,3 @@
 module Historiographer
-  VERSION = "4.1.13"
+  VERSION = "4.1.16"
 end

data/lib/historiographer.rb

@@ -306,6 +306,9 @@ module Historiographer
         # Recursively snapshot associations, avoiding infinite loops
         self.class.reflect_on_all_associations.each do |association|
           associated_records = send(association.name)&.reload
+          if associated_records.respond_to?(:order)
+            associated_records = associated_records.order(id: :asc)
+          end
           Array(associated_records).each do |record|
             model_name = record.class.name
             record_id = record.id

data/spec/db/database.yml

@@ -0,0 +1,27 @@
+development:
+  adapter: postgresql
+  encoding: unicode
+  database: historiographer_development
+  pool: 5
+
+test:
+  adapter: postgresql
+  encoding: unicode
+  database: historiographer_test
+  pool: 5
+
+# mysql_default: &mysql_default
+#   adapter: mysql2
+#   encoding: utf8
+#   username: root
+#   password:
+#   host: 127.0.0.1
+#   port: 3306
+
+# development:
+#   <<: *mysql_default
+#   database: historiographer_development
+
+# test:
+#   <<: *mysql_default
+#   database: historiographer_test

data/spec/db/migrate/20161121212228_create_posts.rb

@@ -0,0 +1,19 @@
+class CreatePosts < ActiveRecord::Migration[5.1]
+  def change
+    create_table :posts do |t|
+      t.string :title, null: false
+      t.text :body, null: false
+      t.integer :author_id, null: false
+      t.boolean :enabled, default: false
+      t.datetime :live_at
+      t.datetime :deleted_at
+
+      t.timestamps
+    end
+
+    add_index :posts, :author_id
+    add_index :posts, :enabled
+    add_index :posts, :live_at
+    add_index :posts, :deleted_at
+  end
+end

data/spec/db/migrate/20161121212229_create_post_histories.rb

@@ -0,0 +1,10 @@
+require "historiographer/postgres_migration"
+require "historiographer/mysql_migration"
+
+class CreatePostHistories < ActiveRecord::Migration[5.1]
+  def change
+    create_table :post_histories do |t|
+      t.histories
+    end
+  end
+end

data/spec/db/migrate/20161121212230_create_authors.rb

@@ -0,0 +1,13 @@
+class CreateAuthors < ActiveRecord::Migration[5.1]
+  def change
+    create_table :authors do |t|
+      t.string :full_name, null: false
+      t.text :bio
+      t.datetime :deleted_at
+
+      t.timestamps
+    end
+
+    add_index :authors, :deleted_at
+  end
+end

data/spec/db/migrate/20161121212231_create_author_histories.rb

@@ -0,0 +1,10 @@
+require "historiographer/postgres_migration"
+require "historiographer/mysql_migration"
+
+class CreateAuthorHistories < ActiveRecord::Migration[5.1]
+  def change
+    create_table :author_histories do |t|
+      t.histories
+    end
+  end
+end

data/spec/db/migrate/20161121212232_create_users.rb

@@ -0,0 +1,9 @@
+require "historiographer/postgres_migration"
+
+class CreateUsers < ActiveRecord::Migration[5.1]
+  def change
+    create_table :users do |t|
+      t.string :name
+    end
+  end
+end

data/spec/db/migrate/20171011194624_create_safe_posts.rb

@@ -0,0 +1,19 @@
+class CreateSafePosts < ActiveRecord::Migration[5.1]
+  def change
+    create_table :safe_posts do |t|
+      t.string :title, null: false
+      t.text :body, null: false
+      t.integer :author_id, null: false
+      t.boolean :enabled, default: false
+      t.datetime :live_at
+      t.datetime :deleted_at
+
+      t.timestamps
+    end
+
+    add_index :safe_posts, :author_id
+    add_index :safe_posts, :enabled
+    add_index :safe_posts, :live_at
+    add_index :safe_posts, :deleted_at
+  end
+end

data/spec/db/migrate/20171011194715_create_safe_post_histories.rb

@@ -0,0 +1,9 @@
+require "historiographer/postgres_migration"
+
+class CreateSafePostHistories < ActiveRecord::Migration[5.1]
+  def change
+    create_table :safe_post_histories do |t|
+      t.histories
+    end
+  end
+end

data/spec/db/migrate/20191024142304_create_thing_with_compound_index.rb

@@ -0,0 +1,10 @@
+class CreateThingWithCompoundIndex < ActiveRecord::Migration[5.2]
+  def change
+    create_table :thing_with_compound_indices do |t|
+      t.string :key
+      t.string :value
+
+      t.index [:key, :value], name: "idx_key_value"
+    end
+  end
+end

data/spec/db/migrate/20191024142352_create_thing_with_compound_index_history.rb

@@ -0,0 +1,11 @@
+require "historiographer/postgres_migration"
+class CreateThingWithCompoundIndexHistory < ActiveRecord::Migration[5.2]
+  def change
+    create_table :thing_with_compound_index_histories do |t|
+      t.histories index_names: {
+        [:key, :value] => "idx_history_k_v",
+        :thing_with_compound_index_id => "idx_k_v_histories"
+      }
+    end
+  end
+end

data/spec/db/migrate/20191024203106_create_thing_without_history.rb

@@ -0,0 +1,7 @@
+class CreateThingWithoutHistory < ActiveRecord::Migration[5.2]
+  def change
+    create_table :thing_without_histories do |t|
+      t.string :name
+    end
+  end
+end

data/spec/db/migrate/20221018204220_create_silent_posts.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateSilentPosts < ActiveRecord::Migration[5.1]
+  def change
+    create_table :silent_posts do |t|
+      t.string :title, null: false
+      t.text :body, null: false
+      t.integer :author_id, null: false
+      t.boolean :enabled, default: false
+      t.datetime :live_at
+      t.datetime :deleted_at
+
+      t.timestamps
+    end
+
+    add_index :silent_posts, :author_id
+    add_index :silent_posts, :enabled
+    add_index :silent_posts, :live_at
+    add_index :silent_posts, :deleted_at
+  end
+end

data/spec/db/migrate/20221018204255_create_silent_post_histories.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'historiographer/postgres_migration'
+
+class CreateSilentPostHistories < ActiveRecord::Migration[5.1]
+  def change
+    create_table :silent_post_histories, &:histories
+  end
+end

data/spec/db/migrate/20241109182017_create_comments.rb

@@ -0,0 +1,13 @@
+class CreateComments < ActiveRecord::Migration[7.1]
+  def change
+    create_table :comments do |t|
+      t.bigint :post_id
+      t.bigint :author_id
+      t.text :body
+      t.timestamps
+
+      t.index :post_id
+      t.index :author_id
+    end
+  end
+end

data/spec/db/migrate/20241109182020_create_comment_histories.rb

@@ -0,0 +1,9 @@
+require 'historiographer/postgres_migration'
+
+class CreateCommentHistories < ActiveRecord::Migration[7.1]
+  def change
+    create_table :comment_histories do |t|
+      t.histories
+    end
+  end
+end

data/spec/db/migrate/20241118000000_add_type_to_posts.rb

@@ -0,0 +1,6 @@
+class AddTypeToPosts < ActiveRecord::Migration[7.1]
+  def change
+    add_column :posts, :type, :string
+    add_index :posts, :type
+  end
+end

data/spec/db/migrate/20241118000001_add_type_to_post_histories.rb

@@ -0,0 +1,5 @@
+class AddTypeToPostHistories < ActiveRecord::Migration[7.0]
+  def change
+    add_column :post_histories, :type, :string
+  end
+end

data/spec/db/migrate/20241118000002_create_ml_models.rb

@@ -0,0 +1,19 @@
+require "historiographer/postgres_migration"
+require "historiographer/mysql_migration"
+
+class CreateMlModels < ActiveRecord::Migration[7.0]
+  def change
+    create_table :ml_models do |t|
+      t.string :name
+      t.string :model_type
+      t.jsonb :parameters
+      t.timestamps
+
+      t.index :model_type
+    end
+
+    create_table :ml_model_histories do |t|
+      t.histories
+    end
+  end
+end