asgard 0.1.2 → 0.3.0

data/README.md

@@ -1,10 +1,33 @@
 # Asgard
 
-A Ruby task runner built on [Thor](https://github.com/rails/thor) for argument handling and [Dagwood](https://github.com/rewindio/dagwood) for dependency ordering.
-
-The name comes from Norse mythology: **Thor** is the CLI framework, **Asgard** is the realm where tasks live, and the task file is named **loki** — because Loki holds all the tricks.
-
-> **Asgard is a wrapper around [Thor](https://github.com/rails/thor).** Anything Thor can do — subcommands, typed options, argument validation, shell completion — is available inside a `.loki` file. Familiarity with Thor's DSL will make you immediately productive with Asgard.
+> [!INFO]
+> See the [CHANGELOG](CHANGELOG.md) for the latest changes. The [examples directory](examples/) contains working `.loki` files demonstrating the full feature set.
+
+<br>
+<table>
+<tr>
+<td width="40%" align="center" valign="top">
+<img src="docs/assets/images/asgard.jpg" alt="Asgard"><br>
+<em>"Loki writes the tricks. Asgard runs them."</em>
+</td>
+<td width="60%" valign="top">
+<strong>Key Features</strong><br>
+
+- <strong>Thor-Powered CLI</strong> — every Thor DSL feature available inside <code>.loki</code> task files<br>
+- <strong>Task Dependencies</strong> — sequential, parallel, and mixed dependency graphs via <code>depends_on</code><br>
+- <strong>Concurrent Execution</strong> — parallel task groups run in native Ruby threads<br>
+- <strong>Subcommands</strong> — group related tasks under a named namespace<br>
+- <strong>Variables</strong> — shared configuration via Ruby class variables (<code>@@name</code>), visible across all tasks and subcommands<br>
+- <strong>Shell Helpers</strong> — <code>sh</code> for any shell command or heredoc; <code>shebang</code> for polyglot scripts<br>
+- <strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code><br>
+- <strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories<br>
+- <strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files, loaded via <code>import</code> from your <code>.loki</code><br>
+- <strong>Built-in Flags</strong> — <code>--debug</code> and <code>--verbose</code> available on every task; <code>--version</code> at the top level<br>
+</td>
+</tr>
+</table>
+
+<p>Asgard is a <a href="https://github.com/rails/thor">Thor</a>-based task runner for Ruby projects. Define tasks in <code>.loki</code> files, declare dependencies between them, and let Asgard handle ordering and concurrent execution. Anything Thor can do — subcommands, typed options, argument validation — is available inside a <code>.loki</code> file.</p>
 
 ## Installation
 
@@ -28,8 +51,8 @@ Every `.loki` file defines tasks as methods inside `class Tasks`. The `Tasks` cl
 
 ```ruby
 class Tasks
-  desc "hello", "Say hello"
-  def hello = sh 'echo "Hello, World!"'
+  desc "Say hello"
+  def hello = puts "Hello, World!"
 end
 ```
 
@@ -44,7 +67,7 @@ Declare positional parameters directly in the method signature. Document them in
 ```ruby
 class Tasks
   desc "hello NAME", "Say hello to NAME"
-  def hello(name = "World") = sh "echo 'Hello, #{name}!'"
+  def hello(name = "World") = puts "Hello, #{name}!"
 end
 ```
 
@@ -55,7 +78,7 @@ asgard hello Alice
 
 ### A task with a formal argument declaration
 
-Use `argument` for richer metadata — type checking, enums, and help text:
+Use `argument` for richer metadata — type checking, enums, and help text. **Warning: `argument` is a class-level declaration that applies to every task in the class**, not just the one below it. It is best suited for single-command CLIs or when every task genuinely shares the same positional input. In multi-task files, prefer method signature parameters instead.
 
 ```ruby
 class Tasks
@@ -65,7 +88,7 @@ class Tasks
            desc:    "Name to greet"
 
   desc "hello NAME", "Say hello to NAME"
-  def hello = sh "echo 'Hello, #{name}!'"
+  def hello = puts "Hello, #{name}!"
 end
 ```
 
@@ -80,7 +103,7 @@ class Tasks
   method_option :count,  aliases: "-n", type: :numeric, default: 1, desc: "Repeat N times"
   def hello(name = "World")
     message = options[:shout] ? "HELLO, #{name.upcase}!" : "Hello, #{name}!"
-    options[:count].times { sh "echo '#{message}'" }
+    options[:count].times { puts message }
   end
 end
 ```
@@ -105,7 +128,7 @@ class Tasks
   method_option :count, aliases: "-n", type: :numeric, default: 1, desc: "Repeat N times"
   def hello(name = "World")
     message = options[:shout] ? "HELLO, #{name.upcase}!" : "Hello, #{name}!"
-    options[:count].times { sh "echo '#{message}'" }
+    options[:count].times { puts message }
   end
 end
 ```
@@ -124,15 +147,15 @@ Bare symbols run one after another in the order declared:
 
 ```ruby
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = sh "rake build"
 
   depends_on :build
-  desc "test", "Run the test suite"
+  desc "Run the test suite"
   def test = sh "rake test"
 
   depends_on :test
-  desc "release", "Publish the gem"
+  desc "Publish the gem"
   def release = sh "bundle exec rake release"
 end
 ```
@@ -147,15 +170,15 @@ Wrap symbols in an array to declare they can run concurrently. Asgard waits for
 
 ```ruby
 class Tasks
-  desc "lint", "Check code style"
+  desc "Check code style"
   def lint = sh "bundle exec rubocop"
 
-  desc "typecheck", "Run type checks"
+  desc "Run type checks"
   def typecheck = sh "bundle exec srb tc"
 
   # lint and typecheck run in parallel, test waits for both
   depends_on [:lint, :typecheck]
-  desc "test", "Run the test suite"
+  desc "Run the test suite"
   def test = sh "bundle exec rake test"
 end
 ```
@@ -170,16 +193,16 @@ Mix bare symbols (sequential) and arrays (parallel) in a single `depends_on` cal
 
 ```ruby
 class Tasks
-  desc "setup",  "Install dependencies"; def setup  = sh "bundle install"
-  desc "lint",   "Check code style";     def lint   = sh "bundle exec rubocop"
-  desc "build",  "Compile assets";       def build  = sh "rake assets:precompile"
-  desc "test",   "Run tests";            def test   = sh "bundle exec rake test"
-  desc "notify", "Post to Slack";        def notify = sh "curl $SLACK_WEBHOOK -d '{\"text\":\"done\"}'"
+  desc "Install dependencies"; def setup  = sh "bundle install"
+  desc "Check code style";     def lint   = sh "bundle exec rubocop"
+  desc "Compile assets";       def build  = sh "rake assets:precompile"
+  desc "Run tests";            def test   = sh "bundle exec rake test"
+  desc "Post to Slack";        def notify = sh "curl $SLACK_WEBHOOK -d '{\"text\":\"done\"}'"
 
   # setup first, then lint+build in parallel, then test, then notify
   depends_on :setup, [:lint, :build], :test, :notify
-  desc "ci", "Full CI pipeline"
-  def ci = sh "echo 'CI complete'"
+  desc "Full CI pipeline"
+  def ci = puts "CI complete"
 end
 ```
 
@@ -201,18 +224,24 @@ asgard ci executes:
 
 ## Variables
 
-`var` declares a named value available to all tasks as a method. Pass a lambda for lazy evaluation — it is called once on first use:
+Shared configuration values are declared as Ruby class variables (`@@name`) at the top of the class body. Use `||=` so the first declaration wins when multiple `.loki` files reopen `Tasks`, and `.freeze` to prevent mutation:
 
 ```ruby
 class Tasks
-  var :app,     "myapp"
-  var :version, -> { `git describe --tags`.strip }
+  @@app     ||= "myapp".freeze
+  @@max_jobs ||= 4
+
+  desc "Create a release tag"
+  def tag = sh "git tag #{@@app}-#{version}"
+
+  private
 
-  desc "tag", "Create a release tag"
-  def tag = sh "git tag #{app}-#{version}"
+  def version = `git describe --tags`.strip
 end
 ```
 
+Class variables are visible in all task instance methods and in subcommand subclasses — unlike class instance variables (`@name`), which are not accessible inside instance methods.
+
 ---
 
 ## Helper methods
@@ -221,13 +250,13 @@ Private methods are callable from any task in the same class but are never regis
 
 ```ruby
 class Tasks
-  desc "build", "Compile and package"
+  desc "Compile and package"
   def build
     compile("src")
     package(version)
   end
 
-  desc "release", "Build and publish"
+  desc "Build and publish"
   def release
     build
     sh "gem push pkg/myapp-#{version}.gem"
@@ -263,7 +292,7 @@ require_relative "shared/helpers"
 class Tasks
   include BuildHelpers
 
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = compile("src")
 end
 ```
@@ -297,7 +326,7 @@ end
 
 ```ruby
 class Tasks
-  desc "setup", "Bootstrap the development environment"
+  desc "Bootstrap the development environment"
   def setup
     sh <<~SHELL
       brew install redis postgresql
@@ -307,7 +336,7 @@ class Tasks
     SHELL
   end
 
-  desc "analyze", "Run Python data analysis"
+  desc "Run Python data analysis"
   def analyze
     shebang :python3, <<~PYTHON
       import json
@@ -316,7 +345,7 @@ class Tasks
     PYTHON
   end
 
-  desc "bundle_assets", "Build frontend assets with esbuild"
+  desc "Build frontend assets with esbuild"
   def bundle_assets
     shebang :node, <<~JS
       const esbuild = require("esbuild")
@@ -328,28 +357,45 @@ end
 
 Supported interpreters: `:python3`, `:python`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`. Any other symbol is passed directly to `system` with a `.tmp` extension.
 
-Pass `silent: true` to suppress the command echo:
+Pass `silent: true` to both `sh` and `shebang` to suppress the script echo:
 
 ```ruby
-def build = sh "rake build", silent: true
+def build   = sh "rake build", silent: true
+def analyze = shebang :python3, <<~PY, silent: true
+  import json
+  print(json.load(open("data.json")))
+PY
 ```
 
 ---
 
 ## Environment variables
 
-`dotenv` loads a `.env` file into the environment before tasks run:
+`dotenv` loads a `.env` file into the environment before tasks run. Use the `env` Kernel method to read environment variables inside task bodies — it accepts a symbol or string and upcases the key automatically:
 
 ```ruby
 class Tasks
   dotenv              # loads .env
   dotenv ".env.local" # or a specific file
 
-  desc "check", "Print the app name from .env"
-  def check = sh "echo $APP_NAME"
+  desc "Start the server"
+  def start
+    sh "puma -p #{env(:port, '3000')} -e #{env(:rack_env, 'development')}"
+  end
+
+  desc "Deploy the app"
+  def deploy
+    sh "cap #{env(:deploy_target)} deploy"  # raises KeyError if DEPLOY_TARGET is unset
+  end
 end
 ```
 
+| Call | Behaviour |
+|------|-----------|
+| `env(:port, "3000")` | Returns `"3000"` when `PORT` is unset |
+| `env(:api_key)` | Raises `KeyError` when `API_KEY` is missing |
+| `env("DATABASE_URL")` | String name works too — always upcased |
+
 ---
 
 ## Command aliases
@@ -362,7 +408,7 @@ class Tasks
   map "--v" => "version"
   map "t"   => "test"
 
-  desc "version", "Print the version"
+  desc "Print the version"
   def version = puts Asgard::VERSION
 end
 ```
@@ -375,10 +421,10 @@ Group related tasks under a common name using Thor's `subcommand` method. Define
 
 ```ruby
 class DeployCommands < Tasks
-  desc "staging", "Deploy to staging"
+  desc "Deploy to staging"
   def staging = sh "cap staging deploy"
 
-  desc "production", "Deploy to production"
+  desc "Deploy to production"
   def production = sh "cap production deploy"
 end
 
@@ -394,20 +440,20 @@ asgard deploy staging
 asgard deploy production
 ```
 
-Subcommand tasks have all the same access to helper methods like `sh`, `shebang`, `depends_on`, `var`, and the built-in `--debug`/`--verbose` class options as normal tasks.
+Subcommand tasks have all the same access to `sh`, `shebang`, `depends_on`, and the built-in `--debug`/`--verbose` class options as normal tasks. `@@` class variables declared on `Tasks` are also visible in subcommand subclasses.
 
 `depends_on` only works within a subcommand group exactly as it does at the top level:
 
 ```ruby
 class DBCommands < Tasks
-  desc "migrate", "Run pending migrations"
+  desc "Run pending migrations"
   def migrate = sh "rails db:migrate"
 
-  desc "seed", "Load seed data"
+  desc "Load seed data"
   def seed = sh "rails db:seed"
 
   depends_on :migrate, :seed
-  desc "reset", "Migrate then seed"
+  desc "Migrate then seed"
   def reset = puts "Done."
 end
 
@@ -443,7 +489,7 @@ Common `method_option` keys: `aliases`, `type`, `default`, `required`, `desc`, `
 
 ## Task files
 
-Asgard searches the current directory and its ancestors for a `.loki` file. That file marks the project root. All `*.loki` files in the same directory are auto-loaded alphabetically before `.loki` is loaded.
+Asgard searches the current directory and its ancestors for a `.loki` file. That file marks the project root. Additional `*.loki` files are loaded only when your `.loki` file explicitly calls `import`.
 
 ### Single file
 
@@ -458,16 +504,23 @@ Split tasks across files — each reopens `class Tasks`:
 
 ```
 myproject/
-  .loki          ← entry point, can be empty
+  .loki          ← entry point; calls import to load task files
   build.loki
   deploy.loki
   test.loki
 ```
 
+The `.loki` entry file must call `import` to load the other task files. It also marks the project root for auto-discovery:
+
+```ruby
+# .loki
+import "*.loki"
+```
+
 ```ruby
 # build.loki
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = sh "rake build"
 end
 ```
@@ -476,7 +529,7 @@ end
 # test.loki
 class Tasks
   depends_on :build
-  desc "test", "Run the test suite"
+  desc "Run the test suite"
   def test = sh "bundle exec rake test"
 end
 ```
@@ -485,21 +538,21 @@ end
 # deploy.loki
 class Tasks
   depends_on :test
-  desc "deploy", "Deploy to production"
+  desc "Deploy to production"
   def deploy = sh "cap production deploy"
 end
 ```
 
-The `.loki` entry point can be completely empty — it only needs to exist to mark the project root.
+In a single-file project, `.loki` can be completely empty — its presence alone marks the project root. In a multi-file project, add at least an `import` call.
 
 ### Explicit loading
 
-Load any Ruby or `.loki` file manually from `.loki`:
+Load any Ruby or `.loki` file manually from `.loki`. Use `require_relative` for plain Ruby; use `import` for `.loki` files (it enforces the extension and is idempotent):
 
 ```ruby
 # .loki
 require_relative "shared/helpers"
-require_relative "ci.loki"
+import "ci.loki"
 
 class Tasks
   # additional tasks
@@ -514,9 +567,8 @@ end
 |---|---|
 | `Asgard.run!(argv)` | Entry point — finds `.loki`, loads task files, starts CLI |
 | `Asgard.find_task_file` | Returns path to `.loki` searching from CWD upward, or nil |
-| `Asgard.load_loki(dir)` | Loads all `*.loki` files in dir alphabetically |
 
-`run!` handles its own errors — a missing `.loki` or a circular dependency both produce a clean one-line message and exit 1.
+`run!` handles its own errors — a missing `.loki`, a circular dependency, or a `depends_on` that names a task that doesn't exist all produce a clean one-line message and exit 1.
 
 ---
 

data/Rakefile

@@ -3,7 +3,7 @@
 require "bundler/gem_tasks"
 require "minitest/test_task"
 
-SIMPLECOV_PRELUDE = <<~RUBY.freeze
+SIMPLECOV_PRELUDE = <<~RUBY
   require "simplecov"
   SimpleCov.start do
     add_filter "/test/"
@@ -15,8 +15,87 @@ Minitest::TestTask.create do |t|
   t.test_prelude = SIMPLECOV_PRELUDE
 end
 
-task quality: :test do
-  sh "flog lib/"
+task default: :test
+
+RUBOCOP_ENV = { "RUBOCOP_CACHE_ROOT" => "tmp/rubocop_cache" }.freeze
+
+desc "Check code style with RuboCop"
+task :rubocop do
+  sh RUBOCOP_ENV, "bundle exec rubocop"
 end
 
-task default: :test
+desc "Auto-correct RuboCop offenses"
+task :rubocop_fix do
+  sh RUBOCOP_ENV, "bundle exec rubocop -a"
+end
+
+desc "Check code complexity with Flog (warn >=20, fail >=50)"
+task :flog_check do
+  require "flog"
+
+  # Target to work toward; methods above this are warned but don't fail the gate.
+  METHOD_WARN = 20.0
+  # Current baseline floor — established from first run. Reduce incrementally.
+  METHOD_FAIL = 50.0
+
+  flogger = Flog.new(all: true)
+  flogger.flog(*Dir.glob("lib/**/*.rb"))
+
+  warnings = []
+  failures = []
+
+  flogger.each_by_score do |method, score|
+    next if method.end_with?("#none")
+    if score > METHOD_FAIL
+      failures << "#{"%.1f" % score}: #{method}"
+    elsif score > METHOD_WARN
+      warnings << "#{"%.1f" % score}: #{method}"
+    end
+  end
+
+  unless warnings.empty?
+    puts "\nFlog warnings (#{METHOD_WARN}–#{METHOD_FAIL}) — target for future refactoring:"
+    warnings.each { |v| puts "  #{v}" }
+  end
+
+  if failures.empty?
+    puts "\nFlog: no methods exceed the failure threshold (>=#{METHOD_FAIL})"
+  else
+    puts "\nFlog failures (>=#{METHOD_FAIL}) — must be refactored:"
+    failures.each { |v| puts "  #{v}" }
+    $stdout.flush
+    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{METHOD_FAIL}"
+  end
+end
+
+desc "Run all quality checks: tests (with coverage), RuboCop, and Flog"
+task :quality do
+  results = {}
+
+  puts "\n#{"=" * 60}"
+  puts "Quality Gate: Tests + Coverage"
+  puts "=" * 60
+  results[:tests] = system("bundle exec rake test") ? :pass : :fail
+
+  puts "\n#{"=" * 60}"
+  puts "Quality Gate: RuboCop"
+  puts "=" * 60
+  results[:rubocop] = system(RUBOCOP_ENV, "bundle exec rubocop") ? :pass : :fail
+
+  puts "\n#{"=" * 60}"
+  puts "Quality Gate: Flog Complexity"
+  puts "=" * 60
+  results[:flog] = system("bundle exec rake flog_check") ? :pass : :fail
+
+  puts "\n#{"=" * 60}"
+  puts "Quality Summary"
+  puts "=" * 60
+  results.each do |gate, status|
+    icon = status == :pass ? "PASS" : "FAIL"
+    puts "  [#{icon}] #{gate}"
+  end
+  puts "=" * 60
+
+  abort "\nQuality gate failed" if results.values.any?(:fail)
+  puts "\nAll quality gates passed."
+end