smriti 0.5.0

data/lib/ext/exception.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Extend the Exception class to add a method for serializing error details.
+class Exception
+  # Serialize the exception into a hash with message, class, and backtrace.
+  #
+  # @return [Hash] serialized error details
+  def mv_serialize_error
+    {
+      message: message,
+      class: self.class.name,
+      backtrace: Array(backtrace)
+    }
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+##
+# Top-level namespace for the smriti engine.
+module Smriti
+  ##
+  # Namespace for Rails generators shipped with the smriti engine.
+  module Generators
+    ##
+    # Rails generator that installs Smriti into a host application by:
+    #
+    # 1. Copying migrations for definitions and run-tracking tables.
+    # 2. Creating an initializer at `config/initializers/smriti.rb`.
+    # 3. Printing a success message with next steps.
+    #
+    # @example Run the installer
+    #   bin/rails g smriti:install
+    #
+    # @see Smriti::MatViewDefinition
+    # @see Smriti::MatViewRun
+    #
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      ##
+      # Directory containing template files for the generator.
+      #
+      # @return [String] absolute path to templates dir
+      #
+      source_root File.expand_path('templates', __dir__)
+
+      ##
+      # Short description shown in `rails g --help`.
+      desc 'Installs Smriti: copies migrations and initializer.'
+
+      ##
+      # Copies all required migrations into the host app.
+      #
+      # @return [void]
+      #
+      def copy_migrations
+        migration_template 'create_mat_view_definitions.rb', 'db/migrate/create_mat_view_definitions.rb'
+        migration_template 'create_mat_view_runs.rb', 'db/migrate/create_mat_view_runs.rb'
+      end
+
+      ##
+      # Creates the engine initializer in the host app.
+      #
+      # @return [void]
+      #
+      def create_initializer
+        copy_file 'smriti_initializer.rb', 'config/initializers/smriti.rb'
+      end
+
+      ##
+      # Prints a success message after installation.
+      #
+      # @return [void]
+      #
+      def show_success_message
+        say "\n✅ Smriti installed! Don't forget to run:  rails db:migrate\n", :green
+      end
+
+      ##
+      # Computes the next migration number for copied migrations.
+      #
+      # Required by Rails to generate timestamped migration filenames.
+      #
+      # @param path [String] destination path for migrations
+      # @return [String] the next migration number (timestamp)
+      #
+      def self.next_migration_number(path)
+        ActiveRecord::Generators::Base.next_migration_number(path)
+      end
+    end
+  end
+end

data/lib/generators/smriti/install/templates/create_mat_view_definitions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+# This migration creates the mat_view_definitions table, which stores definitions for materialised views.
+# It includes fields for the view name, SQL definition, refresh strategy, schedule, unique index columns,
+# dependencies, last refreshed timestamp, and timestamps for creation and updates.
+class CreateMatViewDefinitions < ActiveRecord::Migration[7.1]
+  def change
+    create_table :mat_view_definitions do |t|
+      t.string :name, null: false, comment: 'The name of the materialised view'
+      t.text :sql, null: false, comment: 'The SQL query defining the materialised view'
+      # refresh_strategy can be
+      # regular: 0 - Default strategy, in-place refresh.
+      # concurrent: 1 - Concurrent refresh, requires at least one unique index.
+      # swap: 2 - Swap the materialised view with a new one, uses more memory.
+      t.integer :refresh_strategy, default: 0, null: false,
+                                   comment: 'Strategy for refreshing the materialised view. Options: regular, concurrent, swap'
+      t.string :schedule_cron, comment: 'Cron schedule for automatic refresh of the materialised view'
+      t.jsonb :unique_index_columns, default: [], comment: 'Columns used for unique indexing, if any'
+      t.jsonb :dependencies, default: [],
+                             comment: 'Dependencies of the materialised view, such as other views or tables'
+      t.timestamps
+    end
+  end
+end

data/lib/generators/smriti/install/templates/create_mat_view_runs.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+# This migration creates the mat_view_runs table, which tracks the mutation runs(create,refresh,drop) of materialised views.
+# It includes references to the materialised view definition, status, operation type, timestamps,
+# duration, error messages, and additional metadata.
+class CreateMatViewRuns < ActiveRecord::Migration[7.1]
+  def change
+    create_table :mat_view_runs do |t|
+      t.references :mat_view_definition,
+                   null: false,
+                   foreign_key: true,
+                   comment: 'Reference to the materialised view definition'
+
+      # 0=running, 1=success, 2=failed
+      t.integer  :status, null: false, default: 0, comment: '0=running,1=success,2=failed'
+      # 0=create, 1=refresh, 2=drop
+      t.integer  :operation, null: false, default: 0, comment: '0=create,1=refresh,2=drop'
+      t.datetime :started_at, comment: 'Timestamp when the operation started'
+      t.datetime :finished_at, comment: 'Timestamp when the operation finished'
+      t.integer  :duration_ms, comment: 'Duration of the operation in milliseconds'
+      t.jsonb :error, comment: 'Error details if the operation failed. :message, :class, :backtrace'
+      t.jsonb :meta, null: false, default: {}, comment: 'Additional metadata about the run, such as job ID, row count or parameters'
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/smriti/install/templates/smriti_initializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+Smriti.configure do |config|
+  ### Job Adapter Configuration
+  # Set job adapter for Smriti
+  # This can be set to :active_job, :sidekiq, and :resque,
+  # defaults to :active_job.
+  #
+  # Depending on your application's job processing setup.
+  # Uncomment the line below to set the job adapter.
+  # config.job_adapter = :active_job
+
+  # job_queue is the queue name for the job adapter.
+  # Default is :default.
+  # This is used to specify the queue where Smriti jobs will be enqueued.
+  # Uncomment the line below to set the job queue.
+  # config.job_queue = :default
+end

data/lib/smriti/admin/auth_bridge.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module Smriti
+  module Admin
+    #
+    # Smriti::Admin::AuthBridge
+    # ---------------------------
+    # Bridge module that wires the Smriti admin engine to a **host-provided**
+    # authentication/authorization layer, while providing safe defaults.
+    #
+    # ### How it works
+    # - Includes {Smriti::Admin::DefaultAuth} first (fallback, no-op/hostable).
+    # - Then includes the **host auth module** returned by {.host_auth_module}.
+    #   Because Ruby searches the most recently included module first, the host
+    #   module cleanly **overrides** any defaults from `DefaultAuth`.
+    # - Registers a before_action `authenticate_smriti!`.
+    # - Exposes helpers: `smriti_current_user` and its alias {#user}.
+    #
+    # ### Host integration options (define one of these):
+    # 1) A top-level module:
+    #    ```ruby
+    #    # app/lib/smriti_admin.rb (or any autoloaded path)
+    #    module SmritiAdmin
+    #      def authenticate_smriti!;  end
+    #      def authorize_smriti!(*); end
+    #      def smriti_current_user;  end
+    #    end
+    #    ```
+    # 2) A namespaced module:
+    #    ```ruby
+    #    # app/lib/smriti/admin/host_auth.rb
+    #    module Smriti
+    #      module Admin
+    #        module HostAuth
+    #          def authenticate_smriti!;  end
+    #          def authorize_smriti!(*); end
+    #          def smriti_current_user;  end
+    #        end
+    #      end
+    #    end
+    #    ```
+    #
+    # If neither module is present, a blank `Module.new` is included and the
+    # defaults in {Smriti::Admin::DefaultAuth} remain in effect.
+    #
+    # @see Smriti::Admin::DefaultAuth
+    #
+    module AuthBridge
+      extend ActiveSupport::Concern
+
+      included do
+        # Include defaults first, so the host module (included below) can override.
+        include Smriti::Admin::DefaultAuth
+        include host_auth_module
+
+        before_action :authenticate_smriti!
+        helper_method :smriti_current_user, :user
+      end
+
+      # Convenience alias for `smriti_current_user` exposed to views.
+      #
+      # @return [Object, nil] the current user object as defined by host auth
+      def user = smriti_current_user
+
+      class_methods do
+        # Resolves the host's auth module, if any.
+        #
+        # Lookup order:
+        # 1. `::SmritiAdmin`
+        # 2. `::Smriti::Admin::HostAuth`
+        # 3. Fallback: a blank Module (no overrides)
+        #
+        # @return [Module] the module to include for host auth overrides
+        def host_auth_module
+          if Object.const_defined?('SmritiAdmin')
+            ::SmritiAdmin
+          elsif Object.const_defined?('Smriti') &&
+                Smriti.const_defined?('Admin') &&
+                Smriti::Admin.const_defined?('HostAuth')
+            ::Smriti::Admin::HostAuth
+          else
+            Module.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smriti/admin/default_auth.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module Smriti
+  module Admin
+    # Smriti::Admin::DefaultAuth
+    # ----------------------------
+    # Development-friendly **fallback** authentication/authorization for the Smriti
+    # admin UI. It is included first by {Smriti::Admin::AuthBridge}, and is meant
+    # to be overridden by a host-provided module (`SmritiAdmin` or
+    # `Smriti::Admin::HostAuth`).
+    #
+    # ❗ **Not for production**: this module allows all access and returns a dummy user.
+    #
+    # @see Smriti::Admin::AuthBridge
+    #
+    module DefaultAuth
+      # Minimal stand-in user object used by the default auth.
+      #
+      # @!attribute [rw] email
+      #   @return [String] the email address of the sample user
+      class SampleUser
+        attr_accessor :email
+
+        # @param email [String]
+        def initialize(email) = @email = email
+
+        # @return [String] the user's email
+        def to_s = email
+      end
+
+      # Authenticates the current request.
+      # Always returns true in the default implementation.
+      #
+      # @return [Boolean] true
+      # rubocop:disable Naming/PredicateMethod
+      def authenticate_smriti! = true
+      # rubocop:enable Naming/PredicateMethod
+
+      # Returns the current user object.
+      # In the default implementation this is a {SampleUser}.
+      #
+      # @return [SampleUser]
+      def smriti_current_user = SampleUser.new('sample-user@example.com')
+
+      # Authorizes an action on a record.
+      # Always returns true in the default implementation.
+      #
+      # @param _action [Symbol, String] the attempted action (ignored)
+      # @param _type [Symbol, String] the type of resource (ignored)
+      # @param _record [Object] the target record or symbol (ignored)
+      # @return [Boolean] true
+      # rubocop:disable Naming/PredicateMethod
+      def authorize_smriti!(_action, _type, _record = nil) = true
+      # rubocop:enable Naming/PredicateMethod
+    end
+  end
+end

data/lib/smriti/configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module Smriti
+  ##
+  # Configuration for the Smriti engine.
+  #
+  # This class provides customization points for how Smriti integrates
+  # with background job systems and controls default behavior across
+  # the engine.
+  #
+  # @example Configure in an initializer
+  #   Smriti.configure do |config|
+  #     config.job_adapter = :sidekiq
+  #     config.job_queue   = :low_priority
+  #     config.admin_ui   = { row_count_strategy: :estimated }
+  #   end
+  #
+  # Supported job adapters:
+  # - `:active_job` (default)
+  # - `:sidekiq`
+  # - `:resque`
+  #
+  class Configuration
+    ##
+    # The job adapter to use for enqueuing jobs.
+    #
+    # @return [Symbol] :active_job, :sidekiq, or :resque
+    attr_accessor :job_adapter
+
+    ##
+    # The default queue name to use for jobs.
+    #
+    # @return [Symbol, String]
+    attr_accessor :job_queue
+
+    ##
+    # admin_ui configuration
+    # @return [Hash]
+    attr_accessor :admin_ui
+
+    ##
+    # Initialize with defaults.
+    #
+    # @return [void]
+    def initialize
+      @job_adapter = :active_job
+      @job_queue   = :default
+      @admin_ui    = {
+        row_count_strategy: :none
+      }
+    end
+  end
+end

data/lib/smriti/engine.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+##
+# Smriti is a Rails engine that provides first-class support for
+# PostgreSQL materialised views in Rails applications.
+module Smriti
+  class << self
+    attr_accessor :importmap
+  end
+  ##
+  # Rails Engine for Smriti.
+  #
+  # This engine encapsulates all functionality related to
+  # materialised views, including:
+  # - Defining materialised view definitions
+  # - Creating and refreshing views
+  # - Managing background jobs for refresh/create/delete
+  #
+  # By isolating the namespace, it ensures that routes, models,
+  # and helpers do not conflict with the host application.
+  #
+  # @example Mounting the engine in a Rails application
+  #   # config/routes.rb
+  #   Rails.application.routes.draw do
+  #     mount Smriti::Engine => "/smriti"
+  #   end
+  #
+  class Engine < ::Rails::Engine
+    isolate_namespace Smriti
+
+    initializer 'smriti.load_config' do
+      Smriti.configuration ||= Smriti::Configuration.new
+    end
+
+    initializer 'smriti.javascript' do |app|
+      app.config.assets.paths << root.join('app/javascript')
+    end
+
+    initializer 'smriti.importmap', before: 'importmap' do |_app|
+      next unless defined?(Importmap)
+
+      Smriti.importmap = Importmap::Map.new
+      Smriti.importmap.draw(root.join('config/importmap.rb'))
+      Smriti.importmap.cache_sweeper(watches: root.join('app/javascript'))
+
+      ActiveSupport.on_load(:action_controller_base) do
+        before_action { Smriti.importmap.cache_sweeper.execute_if_updated }
+      end
+    end
+
+    def self.locale_code_mapping
+      @locale_code_mapping ||= begin
+        mappings = Dir[root.join('config', 'locales', '*.yml')].map.to_h do |file|
+          code = File.basename(file, '.yml').to_sym
+          name = I18n.t('i18n.name', locale: code)
+          [code, name]
+        end
+        mappings.sort_by { |code, _name| code.to_s }.to_h
+      end
+    end
+
+    def self.available_locales
+      @available_locales ||= locale_code_mapping.keys.freeze
+    end
+
+    def self.default_locale = :en
+    def self.loaded_spec = Gem.loaded_specs['smriti']
+    def self.project_name = loaded_spec&.name
+    def self.project_version = Smriti::VERSION
+    def self.project_homepage = loaded_spec&.homepage
+    def self.company_name = 'Codevedas Inc.'
+    def self.documentation_uri = loaded_spec&.metadata&.[]('documentation_uri')
+    def self.bug_tracker_uri = loaded_spec&.metadata&.[]('bug_tracker_uri')
+    def self.support_uri = loaded_spec&.metadata&.[]('support_uri')
+    def self.rubygems_uri = loaded_spec&.metadata&.[]('rubygems_uri')
+  end
+end

data/lib/smriti/helpers/ui_test_ids.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module Smriti
+  module Helpers
+    module UiTestIds
+      GEM_LINK = 'gem_link'
+      PROJECT_HOMEPAGE_LINK = 'project_homepage_link'
+      OPEN_ISSUE_LINK = 'open_issue_link'
+      DOCUMENTATION_LINK = 'documentation_link'
+      SUPPORT_LINK = 'support_link'
+
+      DRAWER_REFRESH_LINK = 'drawer_refresh_link'
+      DRAWER_CLOSE_LINK = 'drawer_close_link'
+
+      HEADER_LINK = 'header_link'
+      PREFERENCES_LINK = 'preferences_link'
+
+      DEFINITIONS_TAB_LINK = 'definitions_tab_link'
+      RUNS_TAB_LINK = 'runs_tab_link'
+
+      NEW_DEFINITION_LINK = 'new_definition_link'
+      SUBMIT_BUTTON = 'submit_button'
+      CANCEL_BUTTON = 'cancel_button'
+      VIEW_HISTORY_LINK = 'view_history_link'
+      VIEW_LINK = 'view_link'
+      EDIT_LINK = 'edit_link'
+      DELETE_LINK = 'delete_link'
+      REFRESH_LINK = 'refresh_link'
+      DROP_LINK = 'drop_link'
+      DROP_CASCADE_LINK = 'drop_cascade_link'
+      CREATE_MV_LINK = 'create_mv_link'
+      RESET_FILTERS_LINK = 'reset_filters_link'
+
+      PREFERENCES_SAVE_BUTTON = 'preferences_save_button'
+      PREFERENCES_CANCEL_BUTTON = 'preferences_cancel_button'
+
+      TOGGLE_SORT_BUTTON = 'toggle_sort_button'
+      DT_SEARCH_INPUT = 'dt_search_input'
+      DT_FILTER_SELECT = 'dt_filter_select'
+      DT_CLEAR_SEARCH_BTN = 'dt_clear_search_btn'
+      DT_PAGINATION_BTN = 'dt_pagination_btn'
+    end
+  end
+end

data/lib/smriti/jobs/adapter.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+##
+# Top-level namespace for the smriti engine.
+module Smriti
+  ##
+  # Namespace for job-related utilities and integrations.
+  module Jobs
+    ##
+    # Adapter class for handling job enqueuing across different backends.
+    #
+    # This class abstracts the job enqueueing process so Smriti can work
+    # with multiple background processing frameworks without changing core code.
+    #
+    # Supported adapters (configured via `Smriti.configuration.job_adapter`):
+    # - `:active_job` → {ActiveJob}
+    # - `:sidekiq`   → {Sidekiq::Client}
+    # - `:resque`    → {Resque}
+    #
+    # @example Enqueue via ActiveJob
+    #   Smriti.configuration.job_adapter = :active_job
+    #   Smriti::Jobs::Adapter.enqueue(MyJob, queue: :low, args: [1, "foo"])
+    #
+    # @example Enqueue via Sidekiq
+    #   Smriti.configuration.job_adapter = :sidekiq
+    #   Smriti::Jobs::Adapter.enqueue(MyWorker, queue: :critical, args: [42])
+    #
+    # @example Enqueue via Resque
+    #   Smriti.configuration.job_adapter = :resque
+    #   Smriti::Jobs::Adapter.enqueue(MyWorker, queue: :default, args: %w[a b c])
+    #
+    # @raise [ArgumentError] if the configured adapter is not recognized
+    #
+    class Adapter
+      ##
+      # Enqueue a job across supported backends.
+      #
+      # @api public
+      #
+      # @param job_class [Class] The job or worker class to enqueue.
+      #   - For `:active_job`, this should be a subclass of {ActiveJob::Base}.
+      #   - For `:sidekiq`, this should be a Sidekiq worker class.
+      #   - For `:resque`, this should be a Resque worker class.
+      #
+      # @param queue [String, Symbol] Target queue name.
+      # @param args [Array] Arguments to pass into the job/worker.
+      #
+      # @return [Object] Framework-dependent:
+      #   - For ActiveJob → enqueued {ActiveJob::Base} instance
+      #   - For Sidekiq → job ID hash
+      #   - For Resque → `true` if enqueue succeeded
+      #
+      # @raise [ArgumentError] if the configured adapter is not recognized.
+      #
+      def self.enqueue(job_class, queue:, args: [])
+        queue_str = queue.to_s
+        job_adapter = Smriti.configuration.job_adapter
+
+        case job_adapter
+        when :active_job
+          job_class.set(queue: queue_str).perform_later(*args)
+        when :sidekiq
+          Sidekiq::Client.push(
+            'class' => job_class.name,
+            'queue' => queue_str,
+            'args' => args
+          )
+        when :resque
+          Resque.enqueue_to(queue_str, job_class, *args)
+        else
+          raise ArgumentError, "Unknown job adapter: #{job_adapter.inspect}"
+        end
+      end
+    end
+  end
+end