asgard 0.1.2 → 0.3.0

data/lib/asgard/base.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "thor"
-require "set"
 require "dagwood"
 
 module Asgard
@@ -16,23 +15,30 @@ module Asgard
       def inherited(subclass)
         super
         Asgard::Base.subclasses << subclass
-        subclass.instance_variable_set(:@_deps,         {})
-        subclass.instance_variable_set(:@_vars,         {})
-        subclass.instance_variable_set(:@_pending_deps, [])
-        subclass.instance_variable_set(:@_ran_tasks,    Set.new)
-        subclass.instance_variable_set(:@_ran_mutex,    Mutex.new)
+        subclass.instance_variable_set(:@_deps,              {})
+        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
 
       def _deps
         @_deps ||= {}
       end
 
-      def _vars
-        @_vars ||= {}
+      def _running
+        @_running ||= Set.new
       end
 
-      def _ran_tasks
-        @_ran_tasks ||= Set.new
+      def _done
+        @_done ||= Set.new
+      end
+
+      def _cond
+        @_cond ||= Hash.new { |h, k| h[k] = ConditionVariable.new }
       end
 
       def _ran_mutex
@@ -41,7 +47,11 @@ module Asgard
 
       # Reset execution tracking for a fresh asgard invocation.
       def _reset_ran!
-        _ran_mutex.synchronize { @_ran_tasks = Set.new }
+        _ran_mutex.synchronize do
+          @_running = Set.new
+          @_done    = Set.new
+          @_cond    = Hash.new { |h, k| h[k] = ConditionVariable.new }
+        end
       end
 
       # Translate stages into a DependencyGraph-compatible hash.
@@ -51,7 +61,7 @@ module Asgard
       def _build_dep_graph(stages)
         graph = {}
         stages.each_with_index do |stage, i|
-          prev_stage = i > 0 ? stages[i - 1] : []
+          prev_stage = i.positive? ? stages[i - 1] : []
           stage.each { |task| graph[task] = prev_stage.dup }
         end
         graph
@@ -68,41 +78,100 @@ module Asgard
         @_pending_deps = tasks
       end
 
-      def var(name, value = nil, &block)
-        value = block if block_given?
-        _vars[name.to_sym] = value
-        no_commands do
-          define_method(name) do
-            v = self.class._vars[name.to_sym]
-            v.respond_to?(:call) ? v.call : v
-          end
+      # 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 = {})
+        if description.nil? || description.is_a?(Hash)
+          options = description if description.is_a?(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
 
-      def import(mod)
-        include mod
-      end
-
       def dotenv(path = ".env")
         require "dotenv"
         Dotenv.load(path) if File.exist?(path)
       end
 
+      def default_task(meth = nil)
+        if meth && meth != :none && @_default_task_location
+          here = caller_locations(1, 1).first
+          warn "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 meth && meth != :none
+          @_default_task_location = caller_locations(1, 1).first
+          @_default_task_name     = meth
+        end
+        super
+      end
+
       # Validate the full dep graph for cycles using Dagwood::DependencyGraph.
       def validate_deps!
+        _check_orphaned_deps!
         return if _deps.empty?
 
-        all_tasks  = all_commands.keys.map(&:to_sym)
-        full_graph = all_tasks.each_with_object({}) do |task, hash|
-          hash[task] = _deps.fetch(task, []).flatten
+        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
+
+      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
 
+      def _build_and_sort_graph(all_task_names)
+        full_graph = all_task_names.to_h { |task| [task, _deps.fetch(task, []).flatten] }
         Dagwood::DependencyGraph.new(full_graph).order
-      rescue TSort::Cyclic => e
-        raise Asgard::CircularDependencyError, e.message
       end
 
+      public
+
       def method_added(method_name)
+        if @_pending_single_desc && !no_commands?
+          pending_desc = @_pending_single_desc
+          pending_opts = @_pending_single_desc_opts || {}
+          @_pending_single_desc      = nil
+          @_pending_single_desc_opts = nil
+          desc(method_name.to_s, pending_desc, pending_opts)
+        end
+
+        return super unless @usage
+
         pending = Array(@_pending_deps).dup
         @_pending_deps = []
 
@@ -117,42 +186,78 @@ module Asgard
 
     no_commands do
       # Dispatch hook: resolves and runs all deps (in parallel where declared)
-      # before executing the target command. Thread-safe deduplication via
-      # the class-level _ran_tasks set ensures each task runs at most once.
+      # before executing the target command.
+      #
+      # 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.
       def invoke_command(command, *args)
         $DEBUG   = true if options[:debug]
         $VERBOSE = true if options[:verbose]
         target = command.name.to_sym
+        return unless acquire_run_token(target)
 
-        should_run = self.class._ran_mutex.synchronize do
-          next false if self.class._ran_tasks.include?(target)
-          self.class._ran_tasks.add(target)
-          true
+        begin
+          run_deps_for(target)
+          command.run(self, *args)
+        ensure
+          signal_done(target)
         end
-        return unless should_run
-
-        stages = self.class._deps[target]
-        if stages&.any?
-          graph  = self.class._build_dep_graph(stages)
-          groups = Dagwood::DependencyGraph.new(graph).parallel_order
-
-          groups.each do |group|
-            if group.size > 1
-              threads = group.map { |task| Thread.new { _run_dep(task) } }
-              threads.each(&:join)
-            else
-              _run_dep(group.first)
-            end
-          end
+      end
+    end
+
+    private
+
+    def acquire_run_token(target)
+      self.class._ran_mutex.synchronize do
+        if self.class._done.include?(target)
+          false
+        elsif self.class._running.include?(target)
+          self.class._cond[target].wait(self.class._ran_mutex) until self.class._done.include?(target)
+          false
+        else
+          self.class._running.add(target)
+          true
         end
+      end
+    end
+
+    def run_deps_for(target)
+      stages = self.class._deps[target]
+      return unless stages&.any?
 
-        command.run(self, *args)
+      groups = Dagwood::DependencyGraph.new(self.class._build_dep_graph(stages)).parallel_order
+      groups.each { |group| run_dep_group(group) }
+    end
+
+    def run_dep_group(group)
+      if group.size > 1
+        threads = group.map { |task| Thread.new { run_dep(task) } }
+        errors  = []
+        threads.each { |t| begin; t.join; 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
+      else
+        run_dep(group.first)
       end
+    end
 
-      def _run_dep(task)
-        command = self.class.all_commands[task.to_s]
-        invoke_command(command) if command
+    def signal_done(target)
+      self.class._ran_mutex.synchronize do
+        self.class._done.add(target)
+        self.class._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

data/lib/asgard/kernel_methods.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Kernel
+  def debug?   = $DEBUG
+  def verbose? = $VERBOSE
+  module_function :debug?, :verbose?
+
+  # Fetch an environment variable by symbol or string name.
+  # The name is converted to an uppercase string automatically.
+  # Raises KeyError when the variable is missing and no default is given.
+  def env(name, default = nil)
+    key = name.to_s.upcase
+    default.nil? ? ENV.fetch(key) : ENV.fetch(key, default)
+  end
+  module_function :env
+
+  def loki_up(name = ".loki")
+    dir = Dir.pwd
+    loop do
+      candidate = File.join(dir, name)
+      return candidate if File.exist?(candidate)
+      parent = File.dirname(dir)
+      break if parent == dir
+      dir = parent
+    end
+    nil
+  end
+  module_function :loki_up
+
+  def import(path)
+    path = path.to_s
+    raise ArgumentError, "import: path must end with .loki (got #{path.inspect})" unless path.end_with?(".loki")
+    unless File.absolute_path?(path)
+      caller_dir = File.dirname(caller_locations(1, 1).first.absolute_path)
+      path = File.expand_path(path, caller_dir)
+    end
+    paths = path =~ /[*?\[{]/ ? Dir.glob(path) : [path]
+    loaded = paths.map do |p|
+      if $LOADED_FEATURES.include?(p)
+        warn "import: skip #{p} (already loaded)" if debug?
+        next false
+      end
+      warn "import: #{p}" if verbose? || debug?
+      load p
+      $LOADED_FEATURES << p
+      true
+    end
+    loaded.any?
+  end
+  module_function :import
+
+  def import_up(name = ".loki")
+    if name =~ /[*?\[{]/
+      dir = Dir.pwd
+      loop do
+        matches = Dir.glob(File.join(dir, name))
+        unless matches.empty?
+          warn "import_up: #{name} → #{dir}" if verbose? || debug?
+          return matches.map { |p| import(p) }.any?
+        end
+        parent = File.dirname(dir)
+        break if parent == dir
+        dir = parent
+      end
+      warn "import_up: #{name} not found" if debug?
+      return false
+    end
+    path = loki_up(name)
+    unless path
+      warn "import_up: #{name} not found" if debug?
+      return false
+    end
+    warn "import_up: #{name} → #{path}" if verbose? || debug?
+    import path
+  end
+  module_function :import_up
+end

data/lib/asgard/shell.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'English'
 require "tempfile"
 
 module Asgard
@@ -12,12 +13,12 @@ module Asgard
       $stdout.puts script unless silent
 
       success = if script.include?("\n")
-        system("bash", "-c", script)
-      else
-        system(script)
-      end
+                  system("bash", "-c", script)
+                else
+                  system(script)
+                end
 
-      exit($?.exitstatus) unless success
+      exit($CHILD_STATUS.exitstatus) unless success
     end
 
     # Write +script+ to a tempfile and execute it with +interpreter+.
@@ -32,11 +33,13 @@ module Asgard
       }
       ext = extensions.fetch(interpreter.to_sym, ".tmp")
 
+      $stdout.puts script unless silent
+
       Tempfile.create(["asgard_", ext]) do |f|
         f.write(script)
         f.flush
         system(interpreter.to_s, f.path)
-        exit($?.exitstatus) unless $?.success?
+        exit($CHILD_STATUS.exitstatus) unless $CHILD_STATUS.success?
       end
     end
   end

data/lib/asgard/tasks.rb

@@ -20,9 +20,4 @@ class Tasks < Asgard::Base
     puts Asgard::VERSION
     exit
   end
-
-  private
-
-  def debug?   = $DEBUG
-  def verbose? = $VERBOSE
 end

data/lib/asgard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Asgard
-  VERSION = "0.1.2"
+  VERSION = "0.3.0"
 end

data/lib/asgard.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "asgard/version"
+require_relative "asgard/kernel_methods"
 require_relative "asgard/shell"
 require_relative "asgard/base"
 require_relative "asgard/tasks"
@@ -12,34 +13,22 @@ module Asgard
   # Search the current directory and its ancestors for a .loki task file.
   # Returns the path string, or nil if not found.
   def self.find_task_file
-    dir = Dir.pwd
-    loop do
-      candidate = File.join(dir, ".loki")
-      return candidate if File.exist?(candidate)
-      parent = File.dirname(dir)
-      break if parent == dir
-      dir = parent
-    end
-    nil
-  end
-
-  # Load all *.loki files from dir in alphabetical order.
-  # Each file typically reopens class Tasks to add tasks.
-  # The .loki entry point is excluded — it is loaded separately by run!.
-  def self.load_loki(dir)
-    Dir.glob(File.join(dir, "*.loki")).sort.each { |f| load f }
+    loki_up
   end
 
   # Main entry point invoked by the asgard executable.
   def self.run!(argv)
     abort "asgard: unknown command '#{argv.first}'" if argv.first&.start_with?("_")
     task_file = find_task_file or abort "asgard: no .loki file found in #{Dir.pwd}"
-    load_loki(File.dirname(task_file))
+    before = Asgard::Base.subclasses.dup
     load task_file
-    Tasks.validate_deps!
+    newly_defined = Asgard::Base.subclasses - before
+    (newly_defined + [Tasks]).uniq.each(&:validate_deps!)
     Tasks._reset_ran!
     Tasks.start(argv)
   rescue CircularDependencyError => e
     abort "asgard: circular dependency — #{e.message}"
+  rescue Error => e
+    abort "asgard: #{e.message}"
   end
 end

data/mkdocs.yml

@@ -0,0 +1,164 @@
+# MkDocs Configuration for Asgard Documentation
+site_name: Asgard
+site_description: Thor-based Ruby task runner with dependency graphs and concurrent execution
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/asgard
+copyright: Copyright © 2026 Dewayne VanHoozer
+
+# Repository information
+repo_name: madbomber/asgard
+repo_url: https://github.com/MadBomber/asgard
+edit_uri: edit/main/docs/
+
+# Configuration
+theme:
+  name: material
+
+  # Color scheme
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: indigo
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  # Typography
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  # Logo and icon
+  icon:
+    repo: fontawesome/brands/github
+    logo: material/shield
+
+  # Theme features
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+# Plugins
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - tags
+
+# Extensions
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: madbomber
+      repo: asgard
+      normalize_issue_symbols: true
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+# Extra CSS
+extra_css:
+  - assets/css/custom.css
+
+# Social media and extra configuration
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/MadBomber/asgard
+      name: Asgard on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/asgard
+      name: Asgard on RubyGems
+
+  analytics:
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: Thanks for your feedback! Help us improve by creating an issue.
+
+# Navigation
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Tasks:
+      - Defining Tasks: tasks.md
+      - Dependencies: dependencies.md
+      - Variables: variables.md
+      - Helper Methods: helpers.md
+  - CLI:
+      - Options & Flags: options.md
+      - Subcommands: subcommands.md
+      - Shell Helpers: shell.md
+      - Environment: environment.md
+  - Task Files: task-files.md
+  - API Reference: api.md
+  - Examples: examples.md
+  - Changelog: changelog.md