asgard 0.3.0 → 0.3.2

data/examples/bad.loki

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+# Demonstrates review.md Critical Issue #1: parallel depends_on tasks that
+# write to shared instance state on `self` race each other.
+#
+# quality.loki's *_check tasks each write a *different* named ivar
+# (@test_result, @rubocop_result, ...), so MRI's GVL happens to hide the
+# race in practice — every write lands on a distinct slot. This file
+# isolates the actual hazard by having 4 parallel workers read-modify-write
+# the SAME @hits counter, the way any real *_check task would if it
+# accumulated into one shared results structure instead of one ivar each.
+#
+# `@hits = @hits + 1` is not one atomic operation — it's a read, an add,
+# then a write — and MRI can switch threads between those steps. Thread.pass
+# inside the loop forces exactly those switches, so the lost-update race
+# shows up reliably instead of "most of the time."
+#
+# Run with:
+#   asgard bad_race
+#
+# Expected @hits: 4000 (4 workers x 1000 increments each)
+# Actual: consistently lower — proof of the lost-update race described in
+# review.md item #1.
+
+BAD_RACE_WORKERS = 4
+BAD_RACE_REPS    = 1000
+
+class Tasks
+  desc "Increment the shared @hits counter, unsynchronized (worker)"
+  def racer_1 = bump_shared_counter
+
+  desc "Increment the shared @hits counter, unsynchronized (worker)"
+  def racer_2 = bump_shared_counter
+
+  desc "Increment the shared @hits counter, unsynchronized (worker)"
+  def racer_3 = bump_shared_counter
+
+  desc "Increment the shared @hits counter, unsynchronized (worker)"
+  def racer_4 = bump_shared_counter
+
+  depends_on [:racer_1, :racer_2, :racer_3, :racer_4]
+  desc "Show the lost-update race in @hits"
+  def bad_race
+    expected = BAD_RACE_WORKERS * BAD_RACE_REPS
+    puts "expected @hits == #{expected}, got #{@hits}"
+
+    if @hits == expected
+      puts "no corruption this run — the race is timing-dependent, rerun a few times"
+    else
+      puts "DATA RACE CONFIRMED: #{expected - @hits} update(s) lost"
+    end
+  end
+
+  no_commands do
+    def bump_shared_counter
+      @hits ||= 0
+      BAD_RACE_REPS.times do
+        current = @hits    # read
+        Thread.pass        # force a context switch before the write lands
+        @hits = current + 1 # write — another thread's read may already be stale
+      end
+    end
+  end
+end

data/examples/server_subcommands.loki

@@ -1,29 +1,38 @@
 # frozen_string_literal: true
 # Demonstrates Thor subcommands registered on the top-level Tasks class.
 #
-# The subcommand class inherits from Tasks so it has access to sh, shebang,
-# depends_on, and the built-in --debug/--verbose class options.
+# Port state is persisted to .server.port so stop and restart always
+# operate on the same port the server was started on.
 #
 # Usage:
-#   asgard server          # shows subcommand help
+#   asgard server                    # shows subcommand help
 #   asgard server start
-#   asgard server start 4000 --workers 4 --daemon
+#   asgard server start -p 8000
+#   asgard server start -p 4000 --workers 4 --daemon
+#   asgard server stop
 #   asgard server stop --force
 #   asgard server status
-#   asgard server restart 4000
+#   asgard server restart            # stops then starts on the persisted port
+
+SERVER_PORT_FILE = "tmp/.server.port".freeze
 
 class ServerCommands < Tasks
-  desc "start [PORT]", "Start the server on PORT (default: 3000)"
-  option :daemon,  aliases: "-d", type: :boolean, default: false, desc: "Run as a background daemon"
-  option :workers, aliases: "-w", type: :numeric, default: 2,     desc: "Number of worker processes"
+  default_task :help  # This is the default value for the default_task
+
+  helper(:server_port) {
+    File.exist?(SERVER_PORT_FILE) ? File.read(SERVER_PORT_FILE).strip.to_i : 3000
+  }
+
+  desc "Start the server"
+  option :port,    aliases: "-p", type: :numeric, default: 3000,             desc: "Port to listen on"
+  option :daemon,  aliases: "-d", type: :boolean, default: false,            desc: "Run as a background daemon"
+  option :workers, aliases: "-w", type: :numeric, default: 2,                desc: "Number of worker processes"
   option :log,                    type: :string,  default: "log/server.log",
                                   banner: "FILE", desc:    "Write logs to FILE"
-  def start(port = "3000")
-    puts "Starting server on :%s with %d workers%s" % [
-      port,
-      options[:workers],
-      options[:daemon] ? " (daemon)" : ""
-    ]
+  def start
+    FileUtils.mkdir_p("tmp")
+    File.write(SERVER_PORT_FILE, options[:port].to_s)
+    puts "Starting server on :#{options[:port]} with #{options[:workers]} workers#{options[:daemon] ? " (daemon)" : ""}..."
   end
 
   desc "Stop the running server"
@@ -31,22 +40,22 @@ class ServerCommands < Tasks
   option :wait,                  type: :numeric, default: 30,   desc: "Seconds to wait for shutdown"
   def stop
     if options[:force]
-      puts "Force-stopping server..."
+      puts "Force-stopping server on :#{server_port}..."
     else
-      puts "Gracefully stopping server (timeout: #{options[:wait]}s)..."
+      puts "Gracefully stopping server on :#{server_port} (timeout: #{options[:wait] || 30}s)..."
     end
   end
 
   desc "Show server status and process info"
   def status
-    puts "Checking server status..."
+    puts "Server is listening on :#{server_port}"
   end
 
-  # depends_on works inside subcommand groups — stop runs before start
-  depends_on :stop, :start
-  desc "restart [PORT]", "Restart the server on PORT (stop, then start)"
-  def restart(port = "3000")
-    puts "Server restarted on port #{port}."
+  depends_on :stop
+  desc "Restart the server on the same port it was started on"
+  def restart
+    puts "Starting server on :#{server_port}..."
+    puts "Server restarted."
   end
 end
 

data/gem_tasks.loki

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+# Gem lifecycle tasks — imported by .loki
+
+class Tasks
+  desc "Open IRB console with the gem loaded"
+  def console
+    if File.exist?("bin/console")
+      sh "bin/console"
+    else
+      sh "bundle exec irb -Ilib -r #{@@project}"
+    end
+  end
+
+  desc "Build the gem package"
+  depends_on :quality
+  def build
+    sh "mkdir -p pkg"
+    sh "gem build asgard.gemspec"
+    sh "mv asgard-#{project_version}.gem pkg/"
+  end
+
+  desc "Build and install gem locally"
+  depends_on :build
+  def install
+    sh "gem install pkg/asgard-#{project_version}.gem"
+  end
+
+  desc "release", "Release gem to RubyGems (runs quality gate first)"
+  option :yes, aliases: "-y", type: :boolean, default: false, desc: "Skip confirmation prompt"
+  depends_on :quality
+  def release
+    tag      = "v#{project_version}"
+    gem_file = "pkg/asgard-#{project_version}.gem"
+
+    unless options[:yes]
+      print "Release #{@@project} v#{project_version} to RubyGems? [y/N] "
+      $stdout.flush
+      return puts "Aborted." unless $stdin.gets.strip.downcase == "y"
+    end
+
+    abort "Working directory is not clean — commit or stash changes first." unless `git status --porcelain`.strip.empty?
+    abort "Tag #{tag} already exists." unless `git tag -l #{tag}`.strip.empty?
+
+    sh "mkdir -p pkg"
+    sh "gem build asgard.gemspec"
+    sh "mv asgard-#{project_version}.gem pkg/"
+    sh "git tag #{tag}"
+    sh "git push origin #{tag}"
+    sh "gem push #{gem_file}"
+  end
+end

data/git.loki

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# Per-repo git tasks — imported by .loki
+
+class Tasks
+  desc "Push the current branch to its remote"
+  def push = sh "git push"
+
+  desc "Pull (fast-forward only) from the remote"
+  def pull = sh "git pull --ff-only"
+
+  desc "Fetch from the remote"
+  def fetch = sh "git fetch"
+end

data/lib/asgard/base/dependency_graph.rb

@@ -0,0 +1,124 @@
+# 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 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)] }
+      def depends_on(*tasks)
+        @_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)
+
+          _deps[task] = _stages_from(Array(_call_dep_proc(task, stages_or_proc)))
+        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
+
+      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,65 @@
+# 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 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}"
+          # rubocop:enable Style/StderrPuts
+        end
+        if active
+          @_default_task_location = here
+          @_default_task_name     = meth
+        end
+        super
+      end
+    end
+  end
+end