asgard 0.3.1 → 0.3.3

data/lib/asgard/base/dependency_graph.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Asgard
+  class Base < Thor
+    # Dependency declaration (`depends_on`) and full-graph validation
+    # (`validate_deps!`), backed by stdlib TSort for cycle detection.
+    module DependencyGraph
+      def _deps
+        @_deps ||= {}
+      end
+
+      # Declare dependencies for the next task.
+      # Bare symbols run sequentially; arrays within the splat run in parallel.
+      #
+      #   depends_on :build                          # sequential
+      #   depends_on :build, :lint                   # both sequential
+      #   depends_on [:build, :lint]                 # build and lint in parallel
+      #   depends_on :setup, [:build, :lint], :test  # setup, then build+lint, then test
+      #
+      # A sole Proc/lambda, or a block in place of the splat args, defers
+      # resolution to validate_deps! (after every .loki file has loaded),
+      # instead of now. It must return the same shape the splat form above
+      # would: an array of stages, each a Symbol (sequential) or Array
+      # (parallel group).
+      #
+      #   depends_on -> { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
+      #   depends_on { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
+      def depends_on(*tasks, &block)
+        if block
+          raise Asgard::Error, "depends_on accepts either task arguments or a block, not both" if tasks.any?
+
+          tasks = [block]
+        end
+
+        @_pending_deps = tasks
+      end
+
+      # Validate the full dep graph for cycles using stdlib TSort.
+      def validate_deps!
+        _check_orphaned_deps!
+        return if _deps.empty?
+
+        _resolve_lazy_deps!
+        all_task_names = all_commands.keys.map(&:to_sym)
+        _check_undefined_deps!(all_task_names)
+        _check_dep_arities!
+        _build_and_sort_graph(all_task_names)
+      rescue TSort::Cyclic => e
+        raise Asgard::CircularDependencyError, e.message
+      end
+
+      private
+
+      # Normalizes depends_on's raw splat args into a _deps-ready value: the
+      # sole Proc/lambda unresolved (see #depends_on), or a concrete stage
+      # array.
+      def _normalize_pending_deps(pending)
+        sole = pending.first
+        return sole if pending.size == 1 && sole.respond_to?(:call)
+
+        _stages_from(pending)
+      end
+
+      # Each element is a Symbol (sequential) or Array (parallel group).
+      def _stages_from(list)
+        list.map { |d| Array(d).map(&:to_sym) }
+      end
+
+      # Replaces any Proc-valued _deps entry (see #depends_on) with its
+      # resolved stage array. Runs once, after the full .loki chain has
+      # loaded, so the Proc can safely reference tasks defined in any file.
+      def _resolve_lazy_deps!
+        _deps.each do |task, stages_or_proc|
+          next unless stages_or_proc.respond_to?(:call)
+
+          result = Array(_call_dep_proc(task, stages_or_proc))
+          _validate_dep_shape!(task, result)
+          _deps[task] = _stages_from(result)
+        end
+      end
+
+      def _call_dep_proc(task, dep_proc)
+        dep_proc.call
+      rescue StandardError => e
+        raise Asgard::Error, "depends_on proc for '#{task}' raised #{e.class}: #{e.message}"
+      end
+
+      # A resolved proc/lambda/block result must be an Array of stages, each
+      # either a Symbol/String (sequential) or an Array of Symbol/String
+      # (parallel group) — no deeper nesting, no other leaf types.
+      def _validate_dep_shape!(task, result)
+        result.each { |stage| _validate_dep_stage!(task, stage) }
+      end
+
+      def _validate_dep_stage!(task, stage)
+        case stage
+        when Symbol, String then nil
+        when Array           then stage.each { |leaf| _validate_dep_leaf!(task, leaf) }
+        else
+          raise Asgard::Error,
+                "depends_on proc/block for '#{task}' returned invalid stage #{stage.inspect} " \
+                "(#{stage.class}); expected a Symbol, String, or Array of them"
+        end
+      end
+
+      def _validate_dep_leaf!(task, leaf)
+        return if leaf.is_a?(Symbol) || leaf.is_a?(String)
+
+        raise Asgard::Error,
+              "depends_on proc/block for '#{task}' returned invalid dependency #{leaf.inspect} " \
+              "(#{leaf.class}) in a parallel group; expected a Symbol or String"
+      end
+
+      def _check_orphaned_deps!
+        pending = Array(@_pending_deps)
+        return unless pending.any?
+
+        raise Asgard::Error,
+              "depends_on(#{pending.join(', ')}) declared without a following task definition"
+      end
+
+      def _check_undefined_deps!(all_task_names)
+        undefined = _deps.values.flatten.uniq - all_task_names
+        return unless undefined.any?
+
+        raise Asgard::Error, "undefined task(s) in depends_on: #{undefined.sort.join(', ')}"
+      end
+
+      def _check_dep_arities!
+        _deps.each_value do |stages|
+          stages.flatten.each do |dep|
+            meth = instance_method(dep.to_s)
+            required = meth.parameters.count { |type, _| type == :req }
+            next unless required.positive?
+
+            raise Asgard::Error,
+                  "task '#{dep}' has #{required} required argument(s) and cannot be used as a dependency"
+          end
+        end
+      end
+
+      # Runs a full topological sort purely to raise TSort::Cyclic on a cycle;
+      # the order itself isn't otherwise used (execution order comes from the
+      # stage groups each task's own depends_on declared).
+      def _build_and_sort_graph(all_task_names)
+        full_graph = all_task_names.to_h { |task| [task, _deps.fetch(task) { [] }.flatten] }
+        Graph.new(full_graph).tsort
+      end
+
+      # Minimal TSort-able wrapper around a task => dependency-list Hash.
+      Graph = Struct.new(:edges) do
+        include TSort
+
+        def tsort_each_node(&) = edges.each_key(&)
+        def tsort_each_child(node, &) = edges.fetch(node).each(&)
+      end
+      private_constant :Graph
+    end
+  end
+end

data/lib/asgard/base/dispatch.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Asgard
+  class Base < Thor
+    # Task execution engine: resolves and runs declared dependencies (in
+    # parallel where declared) before the target command runs.
+    #
+    # Completion-based deduplication: a task is only marked done after its
+    # body finishes. Threads that arrive at an already-running shared dep
+    # wait on its ConditionVariable rather than proceeding immediately,
+    # preventing the race where parallel tasks start before a shared dep
+    # has actually completed.
+    module Dispatch
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def _running
+          @_running ||= Set.new
+        end
+
+        def _done
+          @_done ||= Set.new
+        end
+
+        def _cond
+          @_cond ||= Hash.new { |h, k| h[k] = ConditionVariable.new }
+        end
+
+        # Completed tasks' return values, keyed by task name — lets a task
+        # already run by one thread hand its result to another thread that
+        # shares the dependency, without either touching `self`.
+        def _results
+          @_results ||= {}
+        end
+
+        def _ran_mutex
+          @_ran_mutex ||= Mutex.new
+        end
+
+        # Reset execution tracking for a fresh asgard invocation.
+        def _reset_ran!
+          _ran_mutex.synchronize do
+            @_running = Set.new
+            @_done    = Set.new
+            @_cond    = Hash.new { |h, k| h[k] = ConditionVariable.new }
+            @_results = {}
+          end
+        end
+      end
+
+      # Dispatch hook: resolves and runs all deps (in parallel where declared)
+      # before executing the target command.
+      def invoke_command(command, *)
+        $DEBUG   = true if options[:debug]
+        $VERBOSE = true if options[:verbose]
+        target = command.name.to_sym
+        return cached_result(target) unless acquire_run_token(target)
+
+        result = nil
+        begin
+          resolved_deps = run_deps_for(target)
+          result = with_dep_results(resolved_deps) { command.run(self, *) }
+        ensure
+          signal_done(target, result)
+        end
+        result
+      end
+
+      # The results of +target+'s direct dependencies, keyed by task name —
+      # available to a task body while it runs, e.g. `dep_result(:test_check)`.
+      def dep_results
+        Thread.current[:asgard_dep_results] || {}
+      end
+
+      def dep_result(task)
+        dep_results[task.to_sym]
+      end
+
+      private
+
+      def with_dep_results(results)
+        thread   = Thread.current
+        previous = thread[:asgard_dep_results]
+        thread[:asgard_dep_results] = results
+        yield
+      ensure
+        thread[:asgard_dep_results] = previous
+      end
+
+      def cached_result(target)
+        klass = self.class
+        klass._ran_mutex.synchronize { klass._results[target] }
+      end
+
+      def acquire_run_token(target)
+        klass   = self.class
+        mutex   = klass._ran_mutex
+        done    = klass._done
+        running = klass._running
+
+        mutex.synchronize do
+          if done.include?(target)
+            false
+          elsif running.include?(target)
+            klass._cond[target].wait(mutex) until done.include?(target)
+            false
+          else
+            running.add(target)
+            true
+          end
+        end
+      end
+
+      def run_deps_for(target)
+        stages = self.class._deps[target]
+        return {} unless stages&.any?
+
+        stages.each_with_object({}) { |group, acc| acc.merge!(run_dep_group(group)) }
+      end
+
+      def run_dep_group(group)
+        return { group.first => run_dep(group.first) } unless group.size > 1
+
+        threads = group.map { |task| [task, Thread.new { run_dep(task) }] }
+        errors  = []
+        results = {}
+        threads.each do |task, t|
+          results[task] = t.value
+        rescue => e
+          errors << e
+        end
+
+        if errors.size == 1
+          raise errors.first
+        elsif errors.any?
+          errors.each { |e| warn "asgard: #{e.message}" }
+          raise Asgard::Error, "#{errors.size} parallel dependencies failed"
+        end
+
+        results
+      end
+
+      def signal_done(target, result)
+        klass = self.class
+        klass._ran_mutex.synchronize do
+          klass._done.add(target)
+          klass._results[target] = result
+          klass._cond[target].broadcast
+        end
+      end
+
+      def run_dep(task)
+        command = self.class.all_commands[task.to_s]
+        invoke_command(command) if command
+      end
+    end
+  end
+end

data/lib/asgard/base/registry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Asgard
+  class Base < Thor
+    # Tracks every Asgard::Base subclass ever defined, and every method
+    # name's full source_location history — the data Doctor (`asgard
+    # --doctor`) uses to detect a silently-overridden `def`, same file or
+    # across files.
+    module Registry
+      def subclasses
+        @subclasses ||= []
+      end
+
+      def inherited(subclass)
+        super
+        Asgard::Base.subclasses << subclass
+        subclass.instance_variable_set(:@_deps,              {})
+        subclass.instance_variable_set(:@_method_log,        Hash.new { |h, k| h[k] = [] })
+        subclass.instance_variable_set(:@_pending_deps,      [])
+        subclass.instance_variable_set(:@_pending_single_desc,      nil)
+        subclass.instance_variable_set(:@_pending_single_desc_opts, nil)
+        subclass.instance_variable_set(:@_running,    Set.new)
+        subclass.instance_variable_set(:@_done,       Set.new)
+        subclass.instance_variable_set(:@_cond,       Hash.new { |h, k| h[k] = ConditionVariable.new })
+        subclass.instance_variable_set(:@_ran_mutex,  Mutex.new)
+      end
+
+      # Every source_location a method name has ever been defined at, in
+      # definition order — so a later `def` silently overriding an earlier
+      # one (same name, different file) is still visible after the fact.
+      # Doctor is the consumer; asgard itself doesn't otherwise care once
+      # the last definition wins.
+      def _method_log
+        @_method_log ||= Hash.new { |h, k| h[k] = [] }
+      end
+    end
+  end
+end

data/lib/asgard/base/task_dsl.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Asgard
+  class Base < Thor
+    # Task-definition macros available inside .loki files: single-argument
+    # `desc`, `--no-x`/`--skip-x` suppression, `.env` loading, the `helper`
+    # DSL, and `default_task` override warnings.
+    module TaskDSL
+      # Allow single-argument desc: desc "Run the tests"
+      # The usage string defaults to the method name when the description is the only arg.
+      def desc(usage_or_desc, description = nil, options = {})
+        is_hash = description.is_a?(Hash)
+        if description.nil? || is_hash
+          options = description if is_hash
+          @_pending_single_desc      = usage_or_desc
+          @_pending_single_desc_opts = options
+        else
+          @_pending_single_desc      = nil
+          @_pending_single_desc_opts = nil
+          super
+        end
+      end
+
+      # Suppress [--no-name] / [--skip-name] from help for boolean class options
+      # where negation is meaningless. Call after class_option declarations.
+      def no_negate(*names)
+        names.each do |name|
+          opt = class_options[name]
+          next unless opt
+          opt.define_singleton_method(:usage) do |padding = 0|
+            aliases_for_usage.ljust(padding) + "[#{switch_name}]"
+          end
+        end
+      end
+
+      def dotenv(path = ".env")
+        require "dotenv"
+        Dotenv.load(path) if File.exist?(path)
+      end
+
+      def helper(name, &)
+        define_singleton_method(name, &)
+        no_commands { private define_method(name) { |*args, **kwargs, &blk| self.class.send(name, *args, **kwargs, &blk) } }
+      end
+
+      def default_task(meth = nil)
+        active = meth && meth != :none
+        here   = caller_locations(1, 1).first if active
+
+        if active && @_default_task_location
+          # rubocop:disable-next Style/StderrPuts -- warn bypasses $stderr in Ruby 4.0, breaking capture_io in tests
+          $stderr.puts "asgard: default_task :#{meth} at #{here.path}:#{here.lineno} " \
+                       "overrides default_task :#{@_default_task_name} set at " \
+                       "#{@_default_task_location.path}:#{@_default_task_location.lineno}"
+        end
+        if active
+          @_default_task_location = here
+          @_default_task_name     = meth
+        end
+        super
+      end
+    end
+  end
+end