asgard 0.3.0 → 0.3.2

data/lib/asgard/base.rb

@@ -1,173 +1,48 @@
 # frozen_string_literal: true
 
 require "thor"
-require "dagwood"
+require "tsort"
+
+require_relative "base/registry"
+require_relative "base/dependency_graph"
+require_relative "base/task_dsl"
+require_relative "base/dispatch"
 
 module Asgard
   class Base < Thor
     include Asgard::Shell
 
-    class << self
-      def subclasses
-        @subclasses ||= []
-      end
+    extend Registry
+    extend DependencyGraph
+    extend TaskDSL
+    include Dispatch
 
-      def inherited(subclass)
-        super
-        Asgard::Base.subclasses << subclass
-        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 _running
-        @_running ||= Set.new
-      end
-
-      def _done
-        @_done ||= Set.new
-      end
-
-      def _cond
-        @_cond ||= Hash.new { |h, k| h[k] = ConditionVariable.new }
-      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 }
-        end
-      end
-
-      # Translate stages into a DependencyGraph-compatible hash.
-      #
-      #   stages: [[:one], [:two, :three], [:four]]
-      #   → { one: [], two: [:one], three: [:one], four: [:two, :three] }
-      def _build_dep_graph(stages)
-        graph = {}
-        stages.each_with_index do |stage, i|
-          prev_stage = i.positive? ? stages[i - 1] : []
-          stage.each { |task| graph[task] = prev_stage.dup }
-        end
-        graph
-      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
-      def depends_on(*tasks)
-        @_pending_deps = tasks
-      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 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_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"
+    class << self
+      def header(text = nil)
+        return @_header if text.nil?
+        (@_header ||= []) << text
       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(', ')}"
+      def footer(text = nil)
+        return @_footer if text.nil?
+        (@_footer ||= []).unshift(text)
       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?
+      def method_added(method_name)
+        name           = method_name.to_s
+        private_method = name.start_with?("_")
 
-            raise Asgard::Error,
-                  "task '#{dep}' has #{required} required argument(s) and cannot be used as a dependency"
-          end
+        unless private_method
+          loc = instance_method(method_name).source_location
+          _method_log[method_name] << loc if loc
         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
-      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)
+          desc(name, pending_desc, pending_opts)
         end
 
         return super unless @usage
@@ -176,88 +51,35 @@ module Asgard
         @_pending_deps = []
 
         return super if pending.empty?
-        return super if method_name.to_s.start_with?("_")
+        return super if private_method
 
-        # Each element is a Symbol (sequential) or Array (parallel group).
-        _deps[method_name.to_sym] = pending.map { |d| Array(d).map(&:to_sym) }
+        _deps[method_name.to_sym] = _normalize_pending_deps(pending)
         super
       end
     end
 
-    no_commands do
-      # Dispatch hook: resolves and runs all deps (in parallel where declared)
-      # 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)
+    def help(command = nil, subcommand = false) # rubocop:disable Style/OptionalBooleanParameter
+      klass       = self.class
+      top_level   = command.nil?
+      header_text = klass.header
+      footer_text = klass.footer
 
-        begin
-          run_deps_for(target)
-          command.run(self, *args)
-        ensure
-          signal_done(target)
-        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?
-
-      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
+      say header_text.join("\n\n") if header_text && top_level
+      say "\n"
+      super
+      say footer_text.join("\n\n") if footer_text && top_level
     end
 
-    def signal_done(target)
-      self.class._ran_mutex.synchronize do
-        self.class._done.add(target)
-        self.class._cond[target].broadcast
-      end
-    end
+    def tree
+      klass       = self.class
+      header_text = klass.header
+      footer_text = klass.footer
 
-    def run_dep(task)
-      command = self.class.all_commands[task.to_s]
-      invoke_command(command) if command
+      say header_text.join("\n\n") if header_text
+      say "\n"
+      super
+      say "\n"
+      say footer_text.join("\n\n") if footer_text
     end
   end
 end

data/lib/asgard/doctor/report.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Asgard
+  class Doctor
+    # Renders the full doctor report to stdout: findings, the Tasks-by-file
+    # listing, and the closing summary line.
+    module Report
+      private
+
+      def print_report
+        divider = "=" * 60
+        puts "\nasgard doctor -- #{@dir}"
+        puts divider
+        @findings.each { |finding| puts format_finding(finding) }
+        print_task_sections
+        puts divider
+        puts summary_line
+      end
+
+      def print_task_sections
+        return if @task_sections.nil? || @task_sections.empty?
+
+        multi_class = @task_sections.size > 1
+        @task_sections.each do |klass, file_map|
+          header = multi_class ? "Tasks by file (#{klass}):" : "Tasks by file:"
+          puts "\n#{header}"
+          file_map.each { |file, tasks| print_file_tasks(file, tasks) }
+        end
+      end
+
+      def print_file_tasks(file, tasks)
+        puts "\n  #{relative_path(file)}"
+        return puts "    (no tasks defined — imports only)" if tasks.empty?
+
+        width = tasks.map { |name, _, _| name.to_s.length }.max
+        tasks.each { |task| puts format_task_line(file, task, width) }
+      end
+
+      def format_task_line(file, task, width)
+        name, line, status = task
+        text = "    #{name.to_s.ljust(width)}  #{relative_path(file)}:#{line}"
+        text += "   #{status}" if status
+        return colorize(31, text) if status&.start_with?("OVERRIDDEN")
+        return colorize(33, text) if status
+
+        text
+      end
+
+      def format_finding(finding)
+        message = finding.message
+        case finding.level
+        when :error then colorize(31, "  [FAIL] #{message}")
+        when :warn  then colorize(33, "  [WARN] #{message}")
+        else colorize(36, "  [INFO] #{message}")
+        end
+      end
+
+      def summary_line
+        by_level = @findings.group_by(&:level)
+        errors   = (by_level[:error]&.size || 0) + override_count
+        warns    = by_level[:warn]&.size || 0
+        return colorize(32, "No problems found.") if errors.zero? && warns.zero?
+        return colorize(33, "No problems found (#{warns} warning(s)).") if errors.zero?
+
+        colorize(31, "#{errors} problem(s), #{warns} warning(s).")
+      end
+
+      def colorize(code, text)
+        "\e[#{code}m#{text}\e[0m"
+      end
+    end
+  end
+end

data/lib/asgard/doctor/task_sections.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Asgard
+  class Doctor
+    # Builds the "Tasks by file" data: every command grouped by the file
+    # it's defined in, with each definition annotated when a task name has
+    # more than one recorded location (the each/each_gem class of bug) —
+    # earlier ones OVERRIDDEN (dead), the last one the active redefinition.
+    module TaskSections
+      private
+
+      def build_task_sections
+        @task_sections = []
+        return unless @new_subclasses
+
+        @task_sections = @new_subclasses.map { |klass| [klass, class_task_file_map(klass)] }
+      end
+
+      def class_task_file_map(klass)
+        file_map = Hash.new { |h, k| h[k] = [] }
+        @loaded_files.each { |f| file_map[f] }
+
+        commands = klass.all_commands.keys
+        klass._method_log.each do |name, locations|
+          next unless commands.include?(name.to_s)
+
+          locations.each_with_index do |(file, line), idx|
+            file_map[file] << [name, line, task_status(locations, idx)]
+          end
+        end
+        file_map.each_value { |tasks| tasks.sort_by! { |t| t[1] } }
+      end
+
+      def task_status(locations, idx)
+        size = locations.size
+        if idx == size - 1
+          return nil if size == 1
+
+          prev_file, prev_line = locations[idx - 1]
+          "active — redefines #{relative_path(prev_file)}:#{prev_line}"
+        else
+          next_file, next_line = locations[idx + 1]
+          "OVERRIDDEN by #{relative_path(next_file)}:#{next_line} — never callable"
+        end
+      end
+
+      def override_count
+        return 0 unless @task_sections
+
+        @task_sections.sum do |_klass, file_map|
+          file_map.values.flatten(1).count { |t| t[2]&.start_with?("OVERRIDDEN") }
+        end
+      end
+
+      # +file+ is normally absolute (every path Doctor loads is expanded
+      # first), but a method's recorded source_location can be relative if it
+      # was defined by code invoked with a relative path (e.g. `ruby some.rb`
+      # rather than an absolute one) — display it verbatim rather than crash.
+      def relative_path(file)
+        path = Pathname.new(file)
+        return file unless path.absolute?
+
+        path.relative_path_from(Pathname.new(@dir)).to_s
+      end
+    end
+  end
+end

data/lib/asgard/doctor.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "doctor/task_sections"
+require_relative "doctor/report"
+
+module Asgard
+  # Diagnoses .loki resolution, import chains, and task definitions for a
+  # directory — invoked via `asgard --doctor`. Deliberately bypasses the
+  # normal Tasks boot sequence (see Asgard.run!) so it can still report
+  # findings when that sequence would otherwise abort the whole process
+  # (a broken file, a circular dependency, a silently overridden task).
+  class Doctor
+    include TaskSections
+    include Report
+
+    Finding = Struct.new(:level, :message, keyword_init: true)
+
+    def initialize(dir = Dir.pwd)
+      @dir          = File.expand_path(dir)
+      @findings     = []
+      @imports      = []
+      @loaded_files = []
+    end
+
+    def run
+      report_markers
+      load_chain
+      report_imports
+      build_task_sections
+      report_dependencies
+      print_report
+    end
+
+    # Every ".loki" marker from +dir+ up to the filesystem root, nearest
+    # first — mirrors loki_up's walk, but collects every match instead of
+    # stopping at the first (so shadowed ancestor markers can be reported).
+    def self.ancestor_markers(dir)
+      markers = []
+      current = Pathname.new(dir)
+      loop do
+        candidate = current + ".loki"
+        markers << candidate.to_s if candidate.exist?
+        parent = current.parent
+        break if parent == current
+
+        current = parent
+      end
+      markers
+    end
+
+    # method_name => [[file, line], ...] entries defined more than once —
+    # same file or different, a later `def` always silently overrides an
+    # earlier one with the same name.
+    def self.duplicate_methods(method_log)
+      method_log.each_with_object({}) do |(name, locations), acc|
+        acc[name] = locations if locations.size > 1
+      end
+    end
+
+    private
+
+    def report_markers
+      markers = self.class.ancestor_markers(@dir)
+      if markers.empty?
+        @findings << Finding.new(level: :error, message: "no .loki file found in #{@dir} or any ancestor")
+        return
+      end
+
+      @marker = markers.first
+      @findings << Finding.new(level: :info, message: "using .loki marker: #{@marker}")
+      markers[1..].each do |shadowed|
+        @findings << Finding.new(level: :warn, message: "shadowed marker (never reached): #{shadowed}")
+      end
+    end
+
+    def load_chain
+      return unless @marker
+
+      Kernel.prepend(ImportTracer)
+      ImportTracer.doctor = self
+      @loaded_files << @marker
+
+      before = Asgard::Base.subclasses.dup
+      load @marker
+      @new_subclasses = (Asgard::Base.subclasses - before + [Tasks]).uniq
+    rescue StandardError, ScriptError => e
+      @findings << Finding.new(level: :error, message: "load failed: #{e.class}: #{e.message}")
+    ensure
+      ImportTracer.doctor = nil
+    end
+
+    def report_imports
+      @imports.each { |message| @findings << Finding.new(level: :info, message: message) }
+    end
+
+    def report_dependencies
+      return unless @new_subclasses
+
+      @new_subclasses.each do |klass|
+        klass.validate_deps!
+      rescue Asgard::Error => e
+        @findings << Finding.new(level: :error, message: "#{klass} dependency graph: #{e.message}")
+      end
+    end
+
+    def record_import(message, added = [])
+      @imports << message
+      @loaded_files.concat(added)
+    end
+
+    # Prepended onto Kernel for the process lifetime of `asgard --doctor`
+    # (Asgard.run! exits right after Doctor#run, so it's never unprepended)
+    # to observe every import/import_up call, whether typed at the top
+    # level of a .loki file or reached indirectly through another import.
+    module ImportTracer
+      class << self
+        attr_accessor :doctor
+      end
+
+      def import(path)
+        loc    = caller_locations(1, 1).first
+        before = $LOADED_FEATURES.dup
+        result = super(path, from: loc)
+        added  = $LOADED_FEATURES - before
+        ImportTracer.doctor&.send(:record_import, ImportTracer.trace_message("import", path, added), added) unless
+          loc&.absolute_path&.end_with?("kernel_methods.rb")
+        result
+      end
+
+      def import_up(name = ".loki")
+        before = $LOADED_FEATURES.dup
+        result = super
+        added  = $LOADED_FEATURES - before
+        ImportTracer.doctor&.send(:record_import, ImportTracer.trace_message("import_up", name, added), added)
+        result
+      end
+
+      def self.trace_message(verb, arg, added)
+        inspected = arg.inspect
+        return "#{verb} #{inspected} -- nothing new (not found or already loaded)" if added.empty?
+
+        "#{verb} #{inspected} -> #{added.join(', ')}"
+      end
+
+      private :import, :import_up
+    end
+  end
+end

data/lib/asgard/kernel_methods.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "pathname"
+
 module Kernel
   def debug?   = $DEBUG
   def verbose? = $VERBOSE
@@ -15,11 +17,11 @@ module Kernel
   module_function :env
 
   def loki_up(name = ".loki")
-    dir = Dir.pwd
+    dir = Pathname.new(Dir.pwd)
     loop do
-      candidate = File.join(dir, name)
-      return candidate if File.exist?(candidate)
-      parent = File.dirname(dir)
+      candidate = dir + name
+      return candidate if candidate.exist?
+      parent = dir.parent
       break if parent == dir
       dir = parent
     end
@@ -27,11 +29,15 @@ module Kernel
   end
   module_function :loki_up
 
-  def import(path)
+  # +from+ is the call-site location used to resolve a relative +path+. It
+  # defaults to the immediate caller, but is exposed as a keyword so a
+  # wrapper (e.g. Asgard::Doctor's import tracer, prepended via `super`)
+  # can thread through the *real* caller instead of its own frame.
+  def import(path, from: caller_locations(1, 1).first)
     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)
+      caller_dir = File.dirname(from.absolute_path)
       path = File.expand_path(path, caller_dir)
     end
     paths = path =~ /[*?\[{]/ ? Dir.glob(path) : [path]

data/lib/asgard/tasks.rb

@@ -4,6 +4,13 @@
 # It is pre-defined by the gem so .loki files never need to declare a class.
 # Auxiliary *.loki files define modules which are imported into Tasks.
 class Tasks < Asgard::Base
+  header "\nasgard v#{Asgard::VERSION} The Mighty Thor and Loki working for you"
+
+  footer <<~FOOT
+    \nDocumentation ... https://madbomber.github.io/asgard
+    Github Repo ..... https://github.com/MadBomber/asgard\n
+  FOOT
+
   class_option :debug,
                type:    :boolean,
                default: false,
@@ -14,10 +21,15 @@ class Tasks < Asgard::Base
                default: false,
                desc:    "Enable verbose output ($VERBOSE = true)"
 
-  desc "--version", "Show asgard version"
-  map "--version" => :_version
-  def _version
-    puts Asgard::VERSION
-    exit
-  end
+  class_option :version,
+               type:    :boolean,
+               default: false,
+               desc:    "Show asgard version and exit"
+  no_negate :version
+
+  class_option :doctor,
+               type:    :boolean,
+               default: false,
+               desc:    "Diagnose .loki resolution, imports, and task definitions for the CWD, then exit"
+  no_negate :doctor
 end

data/lib/asgard/version.rb

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