dag_me 0.1.0

data/lib/dag_me/graph.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module DagMe
+  # Class-level facade for graph-wide operations, reached via `Model.dag`
+  # (default graph) or `Model.dag(:name)` (named graph):
+  #
+  #   Task.dag.between(a, b)
+  #   Task.dag.edges_among(relation)
+  #   Relay.dag(:power).rebuild!
+  #   Task.dag.valid?
+  #   Task.dag.validate!
+  class Graph
+    attr_reader :model, :config
+
+    def initialize(model, config = nil)
+      @model = model
+      @config = config || model.dag_config
+    end
+
+    def adapter
+      config.adapter
+    end
+
+    # Every node lying on some path from `ancestor` to `descendant`,
+    # both endpoints included.
+    def between(ancestor, descendant)
+      adapter.between(ancestor, descendant)
+    end
+
+    def edges
+      config.edge_class.all
+    end
+
+    # Edges whose both endpoints are inside the given node relation -
+    # the induced subgraph's edge set (for exports, visualization, Kahn
+    # walks in Ruby, ...).
+    def edges_among(relation)
+      edges = config.edge_class
+      sub = relation.select(*config.node_pk_columns).arel.ast
+      endpoint_in = lambda do |columns|
+        tuple = Arel::Nodes::Grouping.new(columns.map { |c| edges.arel_table[c] })
+        Arel::Nodes::In.new(tuple, sub)
+      end
+      edges.where(endpoint_in.call(config.edge_parent_columns))
+           .where(endpoint_in.call(config.edge_child_columns))
+    end
+
+    # Rebuilds the closure table from the edges table. No-op for
+    # maintain: :recursive_cte (there is nothing materialized).
+    def rebuild!
+      return self unless config.closure?
+
+      model.connection_pool.with_connection do |conn|
+        conn.execute("SELECT #{conn.quote_table_name("#{config.prefix}_rebuild_paths")}();")
+      end
+      self
+    end
+
+    # Rows where the stored closure disagrees with the recursive-CTE truth.
+    # Empty means healthy.
+    def validate
+      return [] unless config.closure?
+
+      model.connection_pool.with_connection do |conn|
+        conn.select_all("SELECT * FROM #{conn.quote_table_name("#{config.prefix}_validate_paths")}();").to_a
+      end
+    end
+
+    def valid?
+      validate.empty?
+    end
+
+    def validate!
+      rows = validate
+      if rows.any?
+        raise CorruptionError.new(
+          "dag_me: closure for #{model.name} diverged from edge truth (#{rows.length} rows)", rows
+        )
+      end
+
+      self
+    end
+  end
+end

data/lib/dag_me/macro.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module DagMe
+  module Macro
+    # Declares a DAG on the model. Called bare it defines the model's default
+    # graph; called with a name it defines an independent named graph, so one
+    # node can belong to many networks:
+    #
+    #   class Relay < ApplicationRecord
+    #     dag_me :power
+    #     dag_me :comms, maintain: :recursive_cte
+    #   end
+    #
+    #   relay.add_child(other, dag: :power)
+    #   relay.comms_children
+    #   Relay.dag(:power).rebuild!
+    def dag_me(name = nil, maintain: :postgresql_closure, scope: nil, edge_table: nil, paths_table: nil)
+      key = name&.to_sym || :default
+      unless include?(DagMe::Model)
+        class_attribute :dag_configs, instance_writer: false, instance_predicate: false, default: {}.freeze
+        include DagMe::Model
+      end
+      raise ArgumentError, "#{self.name}: dag #{key.inspect} is already defined" if dag_configs.key?(key)
+
+      config = Configuration.new(model: self, name: name&.to_sym, maintain:, scope:, edge_table:, paths_table:)
+      self.dag_configs = dag_configs.merge(key => config).freeze
+      DagMe::Model.attach(self, config)
+      self
+    end
+  end
+end

data/lib/dag_me/model.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module DagMe
+  module Model
+    extend ActiveSupport::Concern
+
+    # Builds the per-dag machinery: edge/paths constants and associations.
+    # Called by the macro once per dag_me declaration, so a model hosting
+    # several named graphs gets one full set each.
+    def self.attach(model, config)
+      parent_fk = config.composite_pk? ? config.edge_parent_columns.map(&:to_sym) : :parent_id
+      child_fk = config.composite_pk? ? config.edge_child_columns.map(&:to_sym) : :child_id
+      pk_opt = config.composite_pk? ? { primary_key: config.node_pk_columns.map(&:to_sym) } : {}
+
+      child_edges = config.association_name('dag_child_edges')
+      parent_edges = config.association_name('dag_parent_edges')
+
+      edge_class = Class.new(ActiveRecord::Base)
+      model.const_set(config.edge_class_name, edge_class)
+      edge_class.table_name = config.edge_table
+      edge_class.belongs_to :parent, class_name: model.name, foreign_key: parent_fk,
+                                     inverse_of: child_edges, **pk_opt
+      edge_class.belongs_to :child, class_name: model.name, foreign_key: child_fk,
+                                    inverse_of: parent_edges, **pk_opt
+
+      if config.closure?
+        paths_class = Class.new(ActiveRecord::Base)
+        model.const_set(config.paths_class_name, paths_class)
+        paths_class.table_name = config.paths_table
+        paths_class.primary_key = config.paths_ancestor_columns + config.paths_descendant_columns
+      end
+
+      model.has_many child_edges, class_name: "#{model.name}::#{config.edge_class_name}",
+                                  foreign_key: parent_fk, inverse_of: :parent, dependent: nil, **pk_opt
+      model.has_many config.association_name('children'), through: child_edges, source: :child
+      model.has_many parent_edges, class_name: "#{model.name}::#{config.edge_class_name}",
+                                   foreign_key: child_fk, inverse_of: :child, dependent: nil, **pk_opt
+      model.has_many config.association_name('parents'), through: parent_edges, source: :parent
+    end
+
+    included do
+      # A valid topological order: nodes with fewer ancestors always come
+      # before their descendants. Composes with any relation, e.g.
+      # `node.descendants.topologically` or `Relay.topologically(:power)`.
+      scope :topologically, ->(dag_name = nil) { dag(dag_name).adapter.apply_topological_order(all) }
+    end
+
+    class_methods do
+      # Graph-wide operations: Task.dag.between(a, b), Task.dag.rebuild!,
+      # Relay.dag(:power).valid?, Task.dag.edges_among(relation), ...
+      def dag(name = nil)
+        config = dag_config_for(name)
+        @dags ||= {}
+        @dags[name&.to_sym || :default] ||= DagMe::Graph.new(self, config)
+      end
+
+      # The default (unnamed) dag's configuration; nil when the model only
+      # declares named dags.
+      def dag_config
+        dag_configs[:default]
+      end
+
+      def dag_config_for(name)
+        key = name&.to_sym || :default
+        dag_configs.fetch(key) do
+          raise ArgumentError,
+                "#{self.name}: unknown dag #{key.inspect} (defined: #{dag_configs.keys.map(&:inspect).join(', ')})"
+        end
+      end
+
+      def roots(dag: nil)
+        dag_nodes_without(dag_config_for(dag), :edge_child_columns)
+      end
+
+      def leaves(dag: nil)
+        dag_nodes_without(dag_config_for(dag), :edge_parent_columns)
+      end
+
+      private
+
+      # Nodes with no edge row in the given role (child -> roots, parent -> leaves).
+      def dag_nodes_without(config, role)
+        edge = Arel::Table.new(config.edge_table)
+        conds = config.node_pk_columns.zip(config.public_send(role))
+                      .map { |pk, edge_col| edge[edge_col].eq(arel_table[pk]) }.inject(:and)
+        where.not(edge.project(1).where(conds).exists)
+      end
+    end
+
+    def add_child(node, dag: nil)
+      config = self.class.dag_config_for(dag)
+      DagMe.translate_errors { config.edge_class.create!(parent: self, child: node) }
+      node
+    end
+
+    def add_parent(node, dag: nil)
+      config = self.class.dag_config_for(dag)
+      DagMe.translate_errors { config.edge_class.create!(parent: node, child: self) }
+      node
+    end
+
+    def remove_child(node, dag: nil)
+      config = self.class.dag_config_for(dag)
+      DagMe.translate_errors do
+        config.edge_class.where(dag_edge_key(config, parent: self, child: node)).delete_all
+      end
+      node
+    end
+
+    def remove_parent(node, dag: nil)
+      config = self.class.dag_config_for(dag)
+      DagMe.translate_errors do
+        config.edge_class.where(dag_edge_key(config, parent: node, child: self)).delete_all
+      end
+      node
+    end
+
+    def ancestors(dag: nil)
+      self.class.dag(dag).adapter.ancestors(self)
+    end
+
+    def descendants(dag: nil)
+      self.class.dag(dag).adapter.descendants(self)
+    end
+
+    def self_and_ancestors(dag: nil)
+      self.class.dag(dag).adapter.self_and_ancestors(self)
+    end
+
+    def self_and_descendants(dag: nil)
+      self.class.dag(dag).adapter.self_and_descendants(self)
+    end
+
+    def ancestor_of?(node, dag: nil)
+      self.class.dag(dag).adapter.reachable?(self, node)
+    end
+
+    def descendant_of?(node, dag: nil)
+      self.class.dag(dag).adapter.reachable?(node, self)
+    end
+
+    # The induced subgraph rooted here: this node, its descendants, and the
+    # edges among them.
+    def subgraph(dag: nil)
+      self_and_descendants(dag:)
+    end
+
+    def subgraph_edges(dag: nil)
+      self.class.dag(dag).edges_among(self_and_descendants(dag:))
+    end
+
+    def root?(dag: nil)
+      config = self.class.dag_config_for(dag)
+      !public_send(config.association_name('dag_parent_edges')).exists?
+    end
+
+    def leaf?(dag: nil)
+      config = self.class.dag_config_for(dag)
+      !public_send(config.association_name('dag_child_edges')).exists?
+    end
+
+    private
+
+    # {parent_id: ..., child_id: ...} - one pair per pk column for composite keys.
+    def dag_edge_key(config, parent:, child:)
+      config.edge_parent_columns.zip(Array(parent.id))
+            .concat(config.edge_child_columns.zip(Array(child.id)))
+            .to_h
+    end
+  end
+end

data/lib/dag_me/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module DagMe
+  class Railtie < Rails::Railtie # :nodoc:
+    generators do
+      require_relative '../generators/dag_me/migration_generator'
+    end
+
+    rake_tasks do
+      load 'dag_me/railties/tasks.rake'
+    end
+  end
+end

data/lib/dag_me/railties/tasks.rake

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+namespace :dag_me do
+  desc 'Report the health of every dag_me model (tables, triggers, functions, closure)'
+  task status: :environment do
+    Rails.application.eager_load!
+    models = ActiveRecord::Base.descendants.select { |klass| klass.include?(DagMe::Model) }
+    DagMe::TaskHelpers.status(models)
+  end
+
+  desc 'Rebuild the closure table for every dag_me model (or MODEL=Task for one)'
+  task rebuild: :environment do
+    Rails.application.eager_load!
+    models = if ENV['MODEL']
+               model = ENV['MODEL'].constantize
+               abort "#{model.name} is not a dag_me model (no dag_me call)" unless model.include?(DagMe::Model)
+               [model]
+             else
+               ActiveRecord::Base.descendants.select { |klass| klass.include?(DagMe::Model) }
+             end
+    models.each do |model|
+      print "Rebuilding #{model.name}... "
+      model.dag_configs.each_value { |config| model.dag(config.name).rebuild! }
+      puts 'done'
+    end
+  end
+end

data/lib/dag_me/task_helpers.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module DagMe
+  # Backs the `dag_me:status` rake task: a doctor-style report of every
+  # dag_me model's database objects and closure health.
+  module TaskHelpers
+    COLORS = {
+      green: "\e[32m",
+      red: "\e[31m",
+      yellow: "\e[33m",
+      cyan: "\e[36m",
+      reset: "\e[0m"
+    }.freeze
+
+    module_function
+
+    def colorize(text, color)
+      "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+    end
+
+    def ok(text)
+      "#{colorize('✓', :green)} #{text}"
+    end
+
+    def bad(text)
+      "#{colorize('✗', :red)} #{text}"
+    end
+
+    def status(models, io: $stdout)
+      if models.empty?
+        io.puts colorize('No dag_me models found.', :yellow)
+        return
+      end
+
+      models.each { |model| io.puts model_report(model) }
+    end
+
+    def model_report(model)
+      model.dag_configs.each_value.map { |config| config_report(model, config) }.join
+    end
+
+    def config_report(model, config)
+      label = config.default? ? model.name : "#{model.name} [#{config.name}]"
+      lines = ["#{colorize(label, :cyan)} (maintain: #{config.maintain}" \
+               "#{", scope: #{config.scope_columns.join(', ')}" if config.scope_columns.any?})"]
+      lines.concat(table_checks(model, config))
+      lines.concat(trigger_checks(model, config))
+      lines.concat(function_checks(model, config))
+      lines << closure_check(model, config)
+      "#{lines.compact.join("\n  ")}\n"
+    end
+
+    def table_checks(model, config)
+      tables = [config.edge_table]
+      tables << config.paths_table if config.closure?
+      tables.map do |table|
+        if model.connection.table_exists?(table)
+          ok("table #{table}")
+        else
+          bad("table #{table} missing - run the dag_me migration")
+        end
+      end
+    end
+
+    def trigger_checks(model, config)
+      expected = ["#{config.prefix}_edge_insert_check"]
+      if config.closure?
+        expected.push("#{config.prefix}_edge_insert_apply", "#{config.prefix}_edge_delete_apply",
+                      "#{config.prefix}_node_insert", "#{config.prefix}_node_delete")
+      end
+      expected << "#{config.prefix}_node_update" if config.scope_columns.any?
+
+      conn = model.connection
+      installed = conn.select_values(<<~SQL)
+        SELECT t.tgname FROM pg_trigger t
+        JOIN pg_class c ON c.oid = t.tgrelid
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE NOT t.tgisinternal
+          AND n.nspname = ANY (current_schemas(false))
+          AND t.tgname LIKE #{conn.quote("#{config.prefix}\\_%")}
+      SQL
+      (expected - installed).map { |name| bad("trigger #{name} missing") }
+                            .presence || [ok("triggers (#{expected.length})")]
+    end
+
+    def function_checks(model, config)
+      expected = ["#{config.prefix}_lock", "#{config.prefix}_edge_insert_check"]
+      if config.closure?
+        expected.push("#{config.prefix}_edge_insert_apply", "#{config.prefix}_edge_delete_apply",
+                      "#{config.prefix}_node_insert", "#{config.prefix}_node_delete",
+                      "#{config.prefix}_rebuild_paths", "#{config.prefix}_validate_paths")
+      end
+      expected << "#{config.prefix}_node_update" if config.scope_columns.any?
+
+      conn = model.connection
+      installed = conn.select_values(<<~SQL)
+        SELECT p.proname FROM pg_proc p
+        JOIN pg_namespace n ON n.oid = p.pronamespace
+        WHERE n.nspname = ANY (current_schemas(false))
+          AND p.proname LIKE #{conn.quote("#{config.prefix}\\_%")}
+      SQL
+      (expected - installed).map { |name| bad("function #{name} missing") }
+                            .presence || [ok("functions (#{expected.length})")]
+    end
+
+    def closure_check(model, config)
+      return ok('closure: not materialized (recursive_cte)') unless config.closure?
+      return nil unless model.connection.table_exists?(config.paths_table)
+
+      graph = model.dag(config.name)
+      discrepancies = graph.validate
+      if discrepancies.empty?
+        ok("closure valid (#{graph.edges.count} edges)")
+      else
+        facade = config.default? ? 'Model.dag' : "Model.dag(:#{config.name})"
+        bad("closure diverged: #{discrepancies.length} rows - run #{facade}.rebuild!")
+      end
+    end
+  end
+end

data/lib/dag_me/test_helper.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DagMe
+  # Minitest assertions for host applications:
+  #
+  #   class GraphSetupTest < ActiveSupport::TestCase
+  #     include DagMe::TestHelper
+  #
+  #     test 'tasks form a healthy DAG' do
+  #       assert_dag_model Task, maintain: :postgresql_closure
+  #       assert_dag_valid Task
+  #     end
+  #   end
+  module TestHelper
+    # Asserts the class is wired up as a dag_me model, optionally pinning
+    # the maintain mode and scope columns. Pass dag: for a named graph.
+    def assert_dag_model(klass, maintain: nil, scope: nil, dag: nil)
+      assert klass.include?(DagMe::Model), "#{klass} should call dag_me"
+
+      config = klass.dag_config_for(dag)
+      if maintain
+        assert_equal maintain, config.maintain,
+                     "#{klass} should maintain its DAG via #{maintain}"
+      end
+
+      return unless scope
+
+      assert_equal Array(scope).map(&:to_sym), config.scope_columns,
+                   "#{klass} should be scoped by #{Array(scope).join(', ')}"
+    end
+
+    # Asserts the stored closure agrees with the recursive-CTE truth.
+    def assert_dag_valid(klass, dag: nil)
+      discrepancies = klass.dag(dag).validate
+
+      assert_empty discrepancies,
+                   "#{klass} closure diverged from edge truth: #{discrepancies.inspect}"
+    end
+
+    def assert_dag_reachable(ancestor, descendant, dag: nil)
+      assert ancestor.ancestor_of?(descendant, dag:),
+             "expected #{node_label(ancestor)} to reach #{node_label(descendant)}"
+    end
+
+    def refute_dag_reachable(ancestor, descendant, dag: nil)
+      refute ancestor.ancestor_of?(descendant, dag:),
+             "expected #{node_label(ancestor)} not to reach #{node_label(descendant)}"
+    end
+
+    # Asserts the ordered node list is a valid topological order: for every
+    # edge among the listed nodes, the parent appears before the child.
+    def assert_topological_order(model, ordered_nodes, dag: nil)
+      config = model.dag_config_for(dag)
+      position = ordered_nodes.each_with_index.to_h { |node, i| [Array(node.id), i] }
+
+      model.dag(dag).edges.find_each do |edge|
+        parent_key = config.edge_parent_columns.map { |c| edge[c] }
+        child_key = config.edge_child_columns.map { |c| edge[c] }
+        next unless position.key?(parent_key) && position.key?(child_key)
+
+        assert_operator position[parent_key], :<, position[child_key],
+                        "edge #{parent_key.join('/')} -> #{child_key.join('/')} violates topological order"
+      end
+    end
+
+    private
+
+    def node_label(node)
+      "#{node.class.name}##{node.id}"
+    end
+  end
+end

data/lib/dag_me/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DagMe
+  VERSION = '0.1.0'
+end

data/lib/dag_me.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_record'
+
+require_relative 'dag_me/version'
+require_relative 'dag_me/errors'
+require 'dag_me/railtie' if defined?(Rails)
+
+module DagMe
+  extend ActiveSupport::Autoload
+
+  autoload :Configuration
+  autoload :DDL
+  autoload :Graph
+  autoload :Macro
+  autoload :Model
+  autoload :TaskHelpers
+  autoload :TestHelper
+
+  module Adapters
+    extend ActiveSupport::Autoload
+
+    autoload :Base
+    autoload :PostgresqlClosure
+    autoload :RecursiveCte
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  extend DagMe::Macro
+end

data/lib/generators/dag_me/migration_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module DagMe
+  module Generators
+    # rails generate dag_me:migration Task
+    class MigrationGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def create_migration_file
+        migration_template 'install_dag.rb.erb', "db/migrate/install_dag_me_for_#{file_name.pluralize}.rb"
+      end
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/dag_me/templates/install_dag.rb.erb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class InstallDagMeFor<%= class_name.pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def up
+    DagMe::DDL.install!(<%= class_name %>)
+  end
+
+  def down
+    DagMe::DDL.uninstall!(<%= class_name %>)
+  end
+end